Open-Xchange - User contributions [en]

AppSuite:GuardCustomization

2023-05-11T13:38:10Z

Greg.hill:

= Ox Guard Customization =

== Overview ==
Guard uses several templates for emails and the Guest reader. These templates are fully customizable, and can be customized at the global level, but also at the context/user level. Changing images, colors, and layout is easy. Changing the wording is also possible, though the translation tables will then need to be updated.

== Template ID ==
Guard uses a template ID for choosing the templates to use. The template ID can be chosen for a user or context using the configuration cascade.

com.openexchange.guard.templateID=x

For any template below, a customized template can be created with the name x-templatename where x is the integer value of the template ID for the user. For example, if you wanted a custom password template based on the template "passwordtempl.html" for a context of users, you could create a template "2-passwordtempl.html" and assign the value com.openexchange.guard.templateID=2 to the context. Then, Guard will use any templates that start with "2-" for the context.

'''NOTE:'''
If no template ID is specified, or if a file specified by the template ID is not found, then the default template is used. The default is the templates with no number prefix, i.e. "passwordtempl.html"

== Templates ==
=== Emails ===
* guesttempl.html - Email template used when sending to a guest user (not an OX account)
* passwordtempl.html - Template used to send a new password to a guest user. As of 2.8, only used if newGuestsRequirePassword=true is configured
* oxpasswordtempl.html - Email template used when sending a new password to an OX user. No longer used after 2.6
* resettempl.html - Template used when sending a password reset
* guestresettempl.html - Template used when resetting guest account and password recovery is disabled

=== Guest Reader (not used as of 2.10) ===
* reader.html - The main guest reader template. THIS IS NOT CUSTOMIZABLE WITH TEMPLATE ID. GLOBAL CHANGES ONLY. We recommend not changing this file and using the header, footer, and style sheets for branding.
* header.html - Top header bar of the Guest reader
* footer.html - Footer of the Guest reader
* style.css - Style sheet for the Guest reader

== Email Template GetText ==
In the HTML templates, wording is surrounded by a call to gettext, which will get the translation for the user. It is used in a HTML call <$gettext("text here")>
Example:

<$gettext("You have received this email because $from has sent you a secure email message with OX Guard. You will receive a link to the secure message in a separate email.")>

== Variables ==
Some email templates have space for variables depending on their function. The variable name will begin with $ such as the above example $from.

* $from - the sender name
* $productName - defined product name (such as "Guard")
* $plainText - used in first guest email. Plaintext greeting defined by sender
* $url - used in guest emails. The url to link to the share
* $password - used in password reset email

As of 4.0
* $year - current year
* $time - current time, adjusted to the users defined locale
* $dateTime- current date and time

== Guest Reader Translations (Reader is not used as of 2.10) ==
The Guest reader webpage uses i18next for translations. If changing the header and footer such that you need translation, use a call such as

<h2 data-i18n="PIN Required:">PIN Required:</h2>

The "data-i18n" property results in the inner HTML wording being replaced with the translation (if available for the specified language)

=====Guest Translations as of Version 2.4.2-rev8=====
Custom Guest reader translations can be managed by creating a file custom-Lang.json located in the /var/www/html/reader/l10n (on Debian 8)
This custom file should contain only the translations you want to replace in the default translation-Lang.json files.

For example, if you wanted to change the French translation of
"Welcome" from "Bienvenue" to "Bonjour", you would create a file custom-FR_fr.json with the contents

<code>
{
"Welcome" : "Bonjour"
}
</code>

The reader will load the file translations-FR_fr.json first, then it will load custom and overwrite any values found.

= Guard Product Name Customization (2.4 or 2.2.1-8+) =

== Overview ==

The Guard product name can be configured by general setting for smaller deployments, by configuration cascade, or by URL

== Product name by configuration ==

The configuration
com.openexchange.guard.productName
can be defined in the guard-core.properties (2.4) or in the guard.properties file (2.2.1-8). This product name will be passed to the UI.

This value can also be configured at the configuration cascade level

== Product name by URL ==

By editing the file yml located in /opt/open-xchange/etc/as-config.yml the property
guard.productName
can be defined based on the browser URL/IP used to address the OX backend. This product name will the be passed to the UI to be displayed by the user.

AppSuite:OX Guard Configuration 2 10

2023-02-13T13:27:54Z

Greg.hill: /* S3-Storage */

= OX Guard 2.10 Configuration =

There are two main files for configuring OX Guard: <code>guard-api.properties</code> and <code>guard-core.properties</code>. The first configuration file is part of the OX backend and contains properties, among others, that enable the OX Guard functionality for various modules such as Mail and Drive as well as some capabilities. The second configuration file is part of the OX Guard and contains properties that configures the behaviour of the product.

== Configuration File (<code>guard-api.properties</code>) ==

=== Main Properties ===

As of Guard 2.10.7, Guard now supports two types of email encryption, PGP and S/Mime. Prior versions only support PGP.

<source lang="bash">com.openexchange.capability.guard = true</source>
Enables PGP Guard. If not set, no Guard PGP functions will be loaded in the UI. Needed if users should be able to do ANY Guard PGP functions including reading encrypted emails. This level will allow users without "guard-mail" enabled to read emails sent to them, reply to those emails, but not create new emails. Recommended minimum level for all users.

<source lang="bash">com.openexchange.capability.guard-mail = true</source>
Enables the user(s) ability to send PGP encrypted emails. If False but guard enabled, they can read encrypted emails and reply to the original sender, but they cannot compose new emails

<source lang="bash">com.openexchange.capability.guard-drive = true</source>
Enables the drive functionality. If false, user(s) will not be able to decode nor upload new encrypted files

<source lang="bash">com.openexchange.capability.smime = true</source> (as of Guard 2.10.7)
Enables S/MIME for the user. This can be used with or without any of the above PGP capabilities. Will enable sending and receiving of S/MIME encrypted/signed emails.

=== Optional Properties ===

<source lang="bash">com.openexchange.guard.templateID = 0</source>
Define template customization ID for the Guest reader emails, the Guest reader, and system emails. See [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization Customization] for details.

<source lang="bash">com.openexchange.guard.endpoint =</source>
Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8009/guardadmin. By default is empty.

==== Capabilities ====

<source lang="bash">com.openexchange.capability.guard-nodeleterecovery = true</source>
(Guard 2.0) Disable the ability of the user to delete the recovery keys. Makes it impossible to reset password, but also adds level of protection/security

<source lang="bash">com.openexchange.capability.guard-nodeleteprivate = true</source>
(Guard 2.0) Disable the ability of the user to delete their PGP private key. They can revoke it, but not delete the key.

== Configuration File (<code>guard-core.properties</code>) ==

=== Database ===

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname = localhost</source>
The address of the MySQL database for OX Guard data. May be the same as the OX MySQL database.

<source lang="bash">com.openexchange.guard.oxguardDatabaseRead</source>
Optional read-only IP/name for the OX Guard database that might be used in Master-Slave setups.

<source lang="bash">com.openexchange.guard.oxguardShardDatabase</source>
IP/Name for the location of the Guest database shards. Additional shards will be created on this database

<source lang="bash">com.openexchange.guard.oxguardShardRead</source>
Optional read-only IP/name for Guest database shards that might be used in Master-Slave setups.

<source lang="bash">com.openexchange.guard.databaseUsername = username</source>
The username to access the OX Backend and Guard database. This user needs to have select, create, lock, insert, update privileges. Guard database user also should have alter (for updates), drop, index.

<source lang="bash">com.openexchange.guard.databasePassword = password</source>
The password for the databases

=== OX API ===

<source lang="bash">com.openexchange.guard.restApiHostname = localhost</source>
The address for the OX REST API. It would be the location of the OX Backend

<source lang="bash">com.openexchange.guard.OXBackendPort = 8009</source>
The port for the OX Backend. Default is 8009 (which is direct communication with the backend). Could be 80, etc, if going through load balancers

<source lang="bash">com.openexchange.guard.restApiUsername = open-xchange com.openexchange.guard.restApiPassword = secret</source>
Username and password for the REST API

<source lang="bash">com.openexchange.guard.externalEmailURL = example.com/appsuite/api/oxguard/reader/reader.html</source>
When Guard sends an encrypted eMail to members, they may not be using the webmail UI to read the email. A help file is attached, and a link will be provided to log into their webmail to read the encrypted item. This setting is used to point to a generic log in for the webmail system. Sent to multiple recipients, so not customized to the individual recipient.

=== Support API ===

<source lang="bash">com.openexchange.guard.supportapiusername = xxxxx
com.openexchange.guard.supportapipassword = yyyyy</source>
If the support API is to be used, a username and password should be configured.

<source lang="bash">com.openexchange.guard.exposedKeyDurationInHours = 168</source>
When a user is deleted, the Private keys are saved in a temporary deleted Keys table (in case of accidental deletion). If support "exposes" the key, the user can then retrieve it using link generated. For security reasons, this link is only valid for a short period of time. This property defines that duration.

=== File Storage ===

Local/remote storage is required for temporary caching of encrypted emails to guest/non-OX users. This can be an attached local file store, or Amazon S3 compatible object store depending on which <code>open-xchange-guard-*-storage</code> package is installed (<code>file</code> or <code>S3</code>).

==== General Properties ====

<source lang="bash">com.openexchange.guard.guestCleanedAfterDaysOfInactivity=365</source>
Specifies how long emails and guest accounts are maintained for guests that have not had any activity. If the guest has not logged into the Guest account in the configured time, the emails are removed and the Guest account is closed.

=== Storage Specific Properties ===

==== File-Storage ====

<source lang="bash">com.openexchange.guard.storage.file.uploadDirectory = /var/spool/open-xchange/guard/uploads</source>
Defines the temporary upload and cache directory for OX Guard Drive files for <code>open-xchange-guard-file-storage</code> package.
This directory needs to be shared between application servers serving the Guest Reader interface.

==== S3-Storage ====
S3 configuration options if the package <code>open-xchange-guard-s3-storage</code> is selected.

As of 7.10.6, the appsuite middleware should be used for Guard S3 storage. Set up a bucket for Guard to use and configure in the middleware. Then tell Guard which S3 storage to use

<source lang="bash">
com.openexchange.filestore.s3.guardstore.endpoint: "http://somewhere"
com.openexchange.filestore.s3.guardstore.bucketName: "guardstore"
com.openexchange.filestore.s3.guardstore.accessKey: AccessKey
com.openexchange.filestore.s3.guardstore.secretKey: SecretKey
com.openexchange.guard.storage.file.fileStorageType: "s3"

com.openexchange.guard.storage.s3.s3FileStore: "guardstore"
</source>

''Deprecated''
<source lang="bash">com.openexchange.guard.storage.s3.endpoint =
com.openexchange.guard.storage.s3.bucketName =
com.openexchange.guard.storage.s3.region =
com.openexchange.guard.storage.s3.accessKey =
com.openexchange.guard.storage.s3.secretKey =</source>

=== Crypto ===

<source lang="bash">com.openexchange.guard.aesKeyLength=256 (Depreciated)</source>
AES Key length. 256 is preferred, but not supported on all systems. May need to have the [http://www.oracle.com/technetwork/java/javase/downloads/index.html Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files] installed.

<source lang="bash">com.openexchange.guard.rsaKeyLength=2048</source>
RSA key length. Used when creating PGP keys

=== PGP ===

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
List of PGP Public key servers to query for public keys

<source lang="bash">com.openexchange.guard.publicKeyWhitelist</source>
A list of IP addresses of TRUSTED Guard servers. When the public PGP key server is queried, it will normally only find Guard keys that have already been created. If on the whitelist, the Guard server will also query the OX backend to see if the email address exists on the OX system, and if so, will create new keys for the user.

<source lang="bash">com.openexchange.guard.keyValidDays = 3650</source>
PGP keys created will only be valid for this number of days. Default is 10 years. Set to 0 if no expiration date.

<source lang="bash">com.openexchange.guard.pgpCacheDays=7</source>
When looking up remote PGP keys, if found, the keys will be stored in a temporary cache. Set number of days until the cache item is expired and remote lookup is repeated.

<pre>com.openexchange.guard.useStartTLS = true</pre>
Use TLS when delivering to the SMTP server when available

=== S/Mime (as of 2.10.7) ===
<source lang="bash">com.openexchange.smime.checkCRL</source>
Enables or disables checking certificate revocation lists when verifying certificates

<source lang="bash">com.openexchange.smime.caGroupId</source>
Specifies a certificate authority group number to which the user belongs. All users withing that group will trust certificate authorities configured for that group.

=== Autocrypt (as of 2.10.2) ===
<source lang="bash">com.openexchange.guard.autoCryptEnabled</source>
Enables AutoCrypt functionality for Guard. If incoming emails have an AutoCrypt header, the key will be imported. Outgoing emails contain the users public key in an autocrypt header.

<source lang="bash">com.openexchange.guard.autoCryptMutual</source>
On outgoing AutoCrypt headers, specifies desired AutoCrypt mode

=== Email ===

<source lang="bash">com.openexchange.guard.guestSMTPServer=smtp.example.com
com.openexchange.guard.guestSMTPPort=25
com.openexchange.guard.guestSMTPUsername=
com.openexchange.guard.guestSMTPPassword=</source>
SMTP settings for outgoing emails from the guest reader. Emails sent from within the system use the OX Backend. The guest reader, however, sends replies through this SMTP. In addition, password emails (reset, initial) are sent through the SMTP server.

=== Bad Attempts ===

<source lang="bash">com.openexchange.guard.badMinuteLock = 10</source>
Defines how long someone will be locked out after bad attempts. Defaults to 10 minutes.

<source lang="bash">com.openexchange.guard.badPasswordCount = 5</source>
Defines how many times a person can attempt to unlock an encrypted item before being locked out. Defaults to 5 times.

=== RSA Key Generation for PGP keys ===

<source lang="bash">com.openexchange.guard.rsacache = true</source>
RSA keys are pre-generated in the background, encrypted, and stored for future user keys. RSA key generation is the most time consuming function and the RSA cache significantly improves new user creation time.

<source lang="bash">com.openexchange.guard.rsacachecount = 100</source>
Number of RSA keys to pre-generate

<source lang="bash">com.openexchange.guard.keycachecheckinterval = 30</source>
Interval in seconds to check the RSA cache and re-populate if less than rsacachecount.

<source lang="bash">com.openexchange.guard.rsacertainty = 256</source>
Bit certainty for RSA key generation. Higher numbers assure the number is in fact prime but time consuming. Lower is much faster. May need to be lower if not using cache.

=== Passwords ===

<source lang="bash">com.openexchange.guard.newpasslength=8</source>
Length of the randomly generated passwords when a user resets password.

<source lang="bash">com.openexchange.guard.minpasswordlength=6</source>
Minimum password length.

=== Backend ===

<source lang="bash">com.openexchange.guard.oxbackendpath = /ajax/</source>
URL used to communicated directly with the OX backend.

<source lang="bash">com.openexchange.guard.oxbackendidletime = 60</source>
HTTP connections to the backend are kept open for faster response. This is the timeout setting that will close idle connections.

=== Guest Accounts ===

<source lang="bash">com.openexchange.guard.shardsize=1000</source>
Guest users data are placed in databases oxguard_x. After set number of users, another database shard is created

<source lang="bash">com.openexchange.guard.guestCleanedAfterDaysOfInactivity=365</source>
Specifies how long emails and guest accounts are maintained for guests that have not had any
activity. If the guest has not logged into the Guest account in the configured time, the
emails are removed and the Guest account is closed.
0 implies indefinite (no cleaning done). Default 365 days

=== Recovery ===

If you do not want password recovery available, you can disable by adding

<source lang="bash">com.openexchange.guard.noRecovery = true</source>
Keep in mind, that a lost password will result in total loss of encrypted data.

=== Miscellaneous ===

<source lang="bash">com.openexchange.guard.secureReply = true</source>
(since Guard 2.2) Normally, when a person replies from an encrypted email, the reply is automatically encrypted. Set to false to disable this automatic encryption

== SSL ==

Starting with 2.4.0, OX Guard is running inside the OSGi container, meaning that all its servlets are being registered and served by Grizzly.

=== API SSL ===

<source lang="bash">com.openexchange.guard.backendSSL = false</source>
Per default the connection between the Guard backend and the configured Open-Xchange
REST API host is unencrypted. Even though that Guard will never transmit unencrypted
emails to or from the REST API you can optionally encrypt the whole communication between
those two components by using SSL. Please note: Enabling SSL might decrease performance
and/or create more system load due to additional encoding of the HTTP streams.

=== Incoming SSL ===

The communication between the frontend load balancer (Apache or otherwise) to Guard is by default HTTP (if protected network). More information on how to enable SSL you can find [http://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#X-FORWARDED-PROTO_Header here].

AppSuite:GuardCustomization

2023-01-25T15:09:58Z

Greg.hill: /* Guest Reader */

= Ox Guard Customization =

== Overview ==
Guard uses several templates for emails and the Guest reader. These templates are fully customizable, and can be customized at the global level, but also at the context/user level. Changing images, colors, and layout is easy. Changing the wording is also possible, though the translation tables will then need to be updated.

== Template ID ==
Guard uses a template ID for choosing the templates to use. The template ID can be chosen for a user or context using the configuration cascade.

com.openexchange.guard.templateID=x

For any template below, a customized template can be created with the name x-templatename where x is the integer value of the template ID for the user. For example, if you wanted a custom password template based on the template "passwordtempl.html" for a context of users, you could create a template "2-passwordtempl.html" and assign the value com.openexchange.guard.templateID=2 to the context. Then, Guard will use any templates that start with "2-" for the context.

'''NOTE:'''
If no template ID is specified, or if a file specified by the template ID is not found, then the default template is used. The default is the templates with no number prefix, i.e. "passwordtempl.html"

== Templates ==
=== Emails ===
* guesttempl.html - Email template used when sending to a guest user (not an OX account)
* passwordtempl.html - Template used to send a new password to a guest user. As of 2.8, only used if newGuestsRequirePassword=true is configured
* oxpasswordtempl.html - Email template used when sending a new password to an OX user. No longer used after 2.6
* resettempl.html - Template used when sending a password reset
* guestresettempl.html - Template used when resetting guest account and password recovery is disabled

=== Guest Reader (not used as of 2.10) ===
* reader.html - The main guest reader template. THIS IS NOT CUSTOMIZABLE WITH TEMPLATE ID. GLOBAL CHANGES ONLY. We recommend not changing this file and using the header, footer, and style sheets for branding.
* header.html - Top header bar of the Guest reader
* footer.html - Footer of the Guest reader
* style.css - Style sheet for the Guest reader

== Email Template GetText ==
In the HTML templates, wording is surrounded by a call to gettext, which will get the translation for the user. It is used in a HTML call <$gettext("text here")>
Example:

<$gettext("You have received this email because $from has sent you a secure email message with OX Guard. You will receive a link to the secure message in a separate email.")>

== Variables ==
Some email templates have space for variables depending on their function. The variable name will begin with $ such as the above example $from.

== Guest Reader Translations ==
The Guest reader webpage uses i18next for translations. If changing the header and footer such that you need translation, use a call such as

<h2 data-i18n="PIN Required:">PIN Required:</h2>

The "data-i18n" property results in the inner HTML wording being replaced with the translation (if available for the specified language)

=====Guest Translations as of Version 2.4.2-rev8=====
Custom Guest reader translations can be managed by creating a file custom-Lang.json located in the /var/www/html/reader/l10n (on Debian 8)
This custom file should contain only the translations you want to replace in the default translation-Lang.json files.

For example, if you wanted to change the French translation of
"Welcome" from "Bienvenue" to "Bonjour", you would create a file custom-FR_fr.json with the contents

<code>
{
"Welcome" : "Bonjour"
}
</code>

The reader will load the file translations-FR_fr.json first, then it will load custom and overwrite any values found.

= Guard Product Name Customization (2.4 or 2.2.1-8+) =

== Overview ==

The Guard product name can be configured by general setting for smaller deployments, by configuration cascade, or by URL

== Product name by configuration ==

The configuration
com.openexchange.guard.productName
can be defined in the guard-core.properties (2.4) or in the guard.properties file (2.2.1-8). This product name will be passed to the UI.

This value can also be configured at the configuration cascade level

== Product name by URL ==

By editing the file yml located in /opt/open-xchange/etc/as-config.yml the property
guard.productName
can be defined based on the browser URL/IP used to address the OX backend. This product name will the be passed to the UI to be displayed by the user.

AppSuite:OX Guard

2023-01-25T15:06:37Z

Greg.hill: /* External */

= OX Guard (Version 2.10) =

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0 | Installation and information of OX Guard 2.0 - 2.2]]
* [[Appsuite:OX_Guard_2_8 | Installation and information of OX Guard 2.4 - 2.8]]

If upgrading from 2.6 or 2.8, please see
* [[Appsuite:OX_Guard_Upgrade_2_10|Upgrading to 2.10]]

== 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-guard-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code> and <code>open-xchange-guard-ui</code>.

The components required for the OX frontend are: <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files).

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 10.0 (Buster) *Version 2.10.3+ 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/DebianBuster /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBuster /

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 <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* ===

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 <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 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 <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).



=== 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== 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 10.0 (Buster) ===

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/DebianBuster />
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:

$ 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>



=== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration_2_10 Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

Debian GNU/Linux 9.0 and 10.0
<source lang="bash">$ vim /etc/apache2/sites-enabled/000-default.conf</source>

Redhat Enterprise Linux 6/7 or CentOS 6/7
<source lang="bash">$ vim /etc/httpd/conf.d/ox.conf</source>

Add the following section into VirtualHost definition:

<Directory /var/www/html/guard>
Options -Indexes
</Directory>

Debian GNU/Linux 9.0 and 10.0
<source lang="bash">$ vim /etc/apache2/conf-enabled/proxy_http.conf</source>

Redhat Enterprise Linux 6/7 or CentOS 6/7
<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>

<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 <code>ProxyPass /appsuite/api</code> 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

<source lang="bash">$ apachectl restart</source>

=== Open-Xchange Middleware Configuration ===

Edit the <code>guard-api.properties</code> 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 <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</code>
* Guard Docs: <code>com.openexchange.capability.guard-docs</code>

'''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.

'''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: ====

<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>
==== Guard Drive: ====

<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.

=== 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 ===
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.
<code>/opt/open-xchange/etc/share.properties</code>
<source lang="bash">com.openexchange.share.guestCapabilityMode=static
com.openexchange.share.staticGuestCapabilities=guard</source>
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.
<source lang="bash">com.openexchange.share.transientSessions=false</source>

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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).

<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 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>

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
<source lang="bash">ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu</source>
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:

<source lang="bash">
SSLProxyEngine on
<LocationMatch /.well-known/openpgpkey/>
ProxyPass https://ox.example.com/.well-known/openpgpkey/
</LocationMatch>
</source>

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>

==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>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 <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>

==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

=== Mail Filter Integration (2.10.4+) ===

To add additional mail filter tests (verify PGP signature, or encrypt incoming), please see
[[AppSuite:OX_Guard_MailFilter | 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 ===

<code>POST /guardsupport/?action=reset_password</code>

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:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (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 ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

=== Upgrade User (Release 2.10 and later) ===

<code>POST /guardsupport/?action=upgrade_guest</code>

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:

* <code>email</code> - The email address of the Guest user
* <code>user_id</code> – The user's new id
* <code>cid</code> - The user's new context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard

2023-01-25T14:59:53Z

Greg.hill:

= OX Guard (Version 2.10) =

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0 | Installation and information of OX Guard 2.0 - 2.2]]
* [[Appsuite:OX_Guard_2_8 | Installation and information of OX Guard 2.4 - 2.8]]

If upgrading from 2.6 or 2.8, please see
* [[Appsuite:OX_Guard_Upgrade_2_10|Upgrading to 2.10]]

== 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-guard-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code> and <code>open-xchange-guard-ui</code>.

The components required for the OX frontend are: <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files).

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 10.0 (Buster) *Version 2.10.3+ 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/DebianBuster /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBuster /

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 <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* ===

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 <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 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 <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).



=== 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== 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 10.0 (Buster) ===

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/DebianBuster />
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:

$ 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>



=== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration_2_10 Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

Debian GNU/Linux 9.0 and 10.0
<source lang="bash">$ vim /etc/apache2/sites-enabled/000-default.conf</source>

Redhat Enterprise Linux 6/7 or CentOS 6/7
<source lang="bash">$ vim /etc/httpd/conf.d/ox.conf</source>

Add the following section into VirtualHost definition:

<Directory /var/www/html/guard>
Options -Indexes
</Directory>

Debian GNU/Linux 9.0 and 10.0
<source lang="bash">$ vim /etc/apache2/conf-enabled/proxy_http.conf</source>

Redhat Enterprise Linux 6/7 or CentOS 6/7
<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>

<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 <code>ProxyPass /appsuite/api</code> 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

<source lang="bash">$ apachectl restart</source>

=== Open-Xchange Middleware Configuration ===

Edit the <code>guard-api.properties</code> 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 <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</code>
* Guard Docs: <code>com.openexchange.capability.guard-docs</code>

'''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.

'''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: ====

<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>
==== Guard Drive: ====

<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.

=== 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 ===
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.
<code>/opt/open-xchange/etc/share.properties</code>
<source lang="bash">com.openexchange.share.guestCapabilityMode=static
com.openexchange.share.staticGuestCapabilities=guard</source>
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.
<source lang="bash">com.openexchange.share.transientSessions=false</source>

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>

If you would like this Guard installation discoverable as HKP service by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.example.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public 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>

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
<source lang="bash">ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu</source>
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:

<source lang="bash">
SSLProxyEngine on
<LocationMatch /.well-known/openpgpkey/>
ProxyPass https://ox.example.com/.well-known/openpgpkey/
</LocationMatch>
</source>

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>

==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>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 <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>

==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

=== Mail Filter Integration (2.10.4+) ===

To add additional mail filter tests (verify PGP signature, or encrypt incoming), please see
[[AppSuite:OX_Guard_MailFilter | 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 ===

<code>POST /guardsupport/?action=reset_password</code>

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:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (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 ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

=== Upgrade User (Release 2.10 and later) ===

<code>POST /guardsupport/?action=upgrade_guest</code>

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:

* <code>email</code> - The email address of the Guest user
* <code>user_id</code> – The user's new id
* <code>cid</code> - The user's new context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard Smime

2023-01-25T14:47:48Z

Greg.hill: Created page with " = Overview = As of Guard version 2.10.7, users can now be configured to use S/Mime for secure email communications. Prior versions supported PGP only. The user can have onl..."

= Overview =

As of Guard version 2.10.7, users can now be configured to use S/Mime for secure email communications. Prior versions supported PGP only. The user can have only S/Mime as an option, or can be configured to have the option of PGP or S/Mime.

Configuring the users options is done through capabilities. Capability of com.openexchange.capability.smime enables or disables the S/Mime functionality. This can be enabled alone, or in conjunction with the other Guard capabilities.

= Installation =

There are no additional installation steps required for S/Mime support. Guard installation and setup must be completed as normal (initialization of database and files as per the normal setup).

To enable S/Mime, set com.openexchange.capability.smime=true for the user. This can be configured system wide, context wide, or user wide as normal.

= Configuration =

== Supported encryption types ==

The most significant configuration is deciding if the user should have only one option for encryption or if the user should have the choice between PGP and S/Mime. S/Mime requires all users to have uploaded keys created from a certificate authority. As a result, the number of people that can receive encrypted emails is much more limited. PGP, however, can create keys on the fly. Hence PGP can support Guest accounts which allows many more people to receive encrypted emails.

A user with only one choice of encryption will have a very straight-forward experience. Having a choice of PGP and S/Mime would add potential confusion for users if they don't understand the difference. In addition, there may be different encryption passwords for the different types of encryption.

Due to this potential confusion when both types enabled, a setting in the user settings has been added to enable S/Mime. If the user does not check this, then he/she will be treated like they have a PGP only setup.

If the user has both capabilities (smime and guard-mail), and have enabled smime in their settings, they will have to actively choose which encryption to use. Password prompts will specify the type of encryption being used.

== Certificate Authorities ==

By default, Guard will trust the certificate authorities in the default JAVA keystore. A different keystore can be specified in the startup script if a new, more restricted list is created.

Additional certificate authorities can be added to Guard. This is useful if a company uses their own certificate authority, or a third party authority that is not trusted by the default keystore is used.

Imported certificate authorities may not necessarily be trusted system wide. One company may want their own certificate authority, but another company will likely not want to trust those certificates by default.

com.openexchange.smime.caGroupId

specifies a group number that the user should belong to. When a certificate authority certificate is imported using the smime clt, a group ID is specified. Users with this group ID configured will trust the imported certificate authority.

/opt/open-xchange/sbin/smime -A admin -P password -a /path/to/pemFile -g grpId

== Other configurations ==

com.openexchange.smime.checkCRL

Enabled checking certificate revocation lists when verifying certificates. This can significantly slow down Guard response time, as there is an HTTP request sent for the revocation list to each certificate authority. This request is cached for the length of time the response is valid, but can add several seconds to signature verifications and email encryption.

AppSuite:OX Guard Configuration 2 10

2023-01-25T14:37:17Z

Greg.hill:

= OX Guard 2.10 Configuration =

There are two main files for configuring OX Guard: <code>guard-api.properties</code> and <code>guard-core.properties</code>. The first configuration file is part of the OX backend and contains properties, among others, that enable the OX Guard functionality for various modules such as Mail and Drive as well as some capabilities. The second configuration file is part of the OX Guard and contains properties that configures the behaviour of the product.

== Configuration File (<code>guard-api.properties</code>) ==

=== Main Properties ===

As of Guard 2.10.7, Guard now supports two types of email encryption, PGP and S/Mime. Prior versions only support PGP.

<source lang="bash">com.openexchange.capability.guard = true</source>
Enables PGP Guard. If not set, no Guard PGP functions will be loaded in the UI. Needed if users should be able to do ANY Guard PGP functions including reading encrypted emails. This level will allow users without "guard-mail" enabled to read emails sent to them, reply to those emails, but not create new emails. Recommended minimum level for all users.

<source lang="bash">com.openexchange.capability.guard-mail = true</source>
Enables the user(s) ability to send PGP encrypted emails. If False but guard enabled, they can read encrypted emails and reply to the original sender, but they cannot compose new emails

<source lang="bash">com.openexchange.capability.guard-drive = true</source>
Enables the drive functionality. If false, user(s) will not be able to decode nor upload new encrypted files

<source lang="bash">com.openexchange.capability.smime = true</source> (as of Guard 2.10.7)
Enables S/MIME for the user. This can be used with or without any of the above PGP capabilities. Will enable sending and receiving of S/MIME encrypted/signed emails.

=== Optional Properties ===

<source lang="bash">com.openexchange.guard.templateID = 0</source>
Define template customization ID for the Guest reader emails, the Guest reader, and system emails. See [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization Customization] for details.

<source lang="bash">com.openexchange.guard.endpoint =</source>
Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8009/guardadmin. By default is empty.

==== Capabilities ====

<source lang="bash">com.openexchange.capability.guard-nodeleterecovery = true</source>
(Guard 2.0) Disable the ability of the user to delete the recovery keys. Makes it impossible to reset password, but also adds level of protection/security

<source lang="bash">com.openexchange.capability.guard-nodeleteprivate = true</source>
(Guard 2.0) Disable the ability of the user to delete their PGP private key. They can revoke it, but not delete the key.

== Configuration File (<code>guard-core.properties</code>) ==

=== Database ===

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname = localhost</source>
The address of the MySQL database for OX Guard data. May be the same as the OX MySQL database.

<source lang="bash">com.openexchange.guard.oxguardDatabaseRead</source>
Optional read-only IP/name for the OX Guard database that might be used in Master-Slave setups.

<source lang="bash">com.openexchange.guard.oxguardShardDatabase</source>
IP/Name for the location of the Guest database shards. Additional shards will be created on this database

<source lang="bash">com.openexchange.guard.oxguardShardRead</source>
Optional read-only IP/name for Guest database shards that might be used in Master-Slave setups.

<source lang="bash">com.openexchange.guard.databaseUsername = username</source>
The username to access the OX Backend and Guard database. This user needs to have select, create, lock, insert, update privileges. Guard database user also should have alter (for updates), drop, index.

<source lang="bash">com.openexchange.guard.databasePassword = password</source>
The password for the databases

=== OX API ===

<source lang="bash">com.openexchange.guard.restApiHostname = localhost</source>
The address for the OX REST API. It would be the location of the OX Backend

<source lang="bash">com.openexchange.guard.OXBackendPort = 8009</source>
The port for the OX Backend. Default is 8009 (which is direct communication with the backend). Could be 80, etc, if going through load balancers

<source lang="bash">com.openexchange.guard.restApiUsername = open-xchange com.openexchange.guard.restApiPassword = secret</source>
Username and password for the REST API

<source lang="bash">com.openexchange.guard.externalEmailURL = example.com/appsuite/api/oxguard/reader/reader.html</source>
When Guard sends an encrypted eMail to members, they may not be using the webmail UI to read the email. A help file is attached, and a link will be provided to log into their webmail to read the encrypted item. This setting is used to point to a generic log in for the webmail system. Sent to multiple recipients, so not customized to the individual recipient.

=== Support API ===

<source lang="bash">com.openexchange.guard.supportapiusername = xxxxx
com.openexchange.guard.supportapipassword = yyyyy</source>
If the support API is to be used, a username and password should be configured.

<source lang="bash">com.openexchange.guard.exposedKeyDurationInHours = 168</source>
When a user is deleted, the Private keys are saved in a temporary deleted Keys table (in case of accidental deletion). If support "exposes" the key, the user can then retrieve it using link generated. For security reasons, this link is only valid for a short period of time. This property defines that duration.

=== File Storage ===

Local/remote storage is required for temporary caching of encrypted emails to guest/non-OX users. This can be an attached local file store, or Amazon S3 compatible object store depending on which <code>open-xchange-guard-*-storage</code> package is installed (<code>file</code> or <code>S3</code>).

==== General Properties ====

<source lang="bash">com.openexchange.guard.guestCleanedAfterDaysOfInactivity=365</source>
Specifies how long emails and guest accounts are maintained for guests that have not had any activity. If the guest has not logged into the Guest account in the configured time, the emails are removed and the Guest account is closed.

=== Storage Specific Properties ===

==== File-Storage ====

<source lang="bash">com.openexchange.guard.storage.file.uploadDirectory = /var/spool/open-xchange/guard/uploads</source>
Defines the temporary upload and cache directory for OX Guard Drive files for <code>open-xchange-guard-file-storage</code> package.
This directory needs to be shared between application servers serving the Guest Reader interface.

==== S3-Storage ====

<source lang="bash">com.openexchange.guard.storage.s3.endpoint =
com.openexchange.guard.storage.s3.bucketName =
com.openexchange.guard.storage.s3.region =
com.openexchange.guard.storage.s3.accessKey =
com.openexchange.guard.storage.s3.secretKey =</source>
S3 configuration options if the package <code>open-xchange-guard-s3-storage</code> is selected.

=== Crypto ===

<source lang="bash">com.openexchange.guard.aesKeyLength=256 (Depreciated)</source>
AES Key length. 256 is preferred, but not supported on all systems. May need to have the [http://www.oracle.com/technetwork/java/javase/downloads/index.html Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files] installed.

<source lang="bash">com.openexchange.guard.rsaKeyLength=2048</source>
RSA key length. Used when creating PGP keys

=== PGP ===

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
List of PGP Public key servers to query for public keys

<source lang="bash">com.openexchange.guard.publicKeyWhitelist</source>
A list of IP addresses of TRUSTED Guard servers. When the public PGP key server is queried, it will normally only find Guard keys that have already been created. If on the whitelist, the Guard server will also query the OX backend to see if the email address exists on the OX system, and if so, will create new keys for the user.

<source lang="bash">com.openexchange.guard.keyValidDays = 3650</source>
PGP keys created will only be valid for this number of days. Default is 10 years. Set to 0 if no expiration date.

<source lang="bash">com.openexchange.guard.pgpCacheDays=7</source>
When looking up remote PGP keys, if found, the keys will be stored in a temporary cache. Set number of days until the cache item is expired and remote lookup is repeated.

<pre>com.openexchange.guard.useStartTLS = true</pre>
Use TLS when delivering to the SMTP server when available

=== S/Mime (as of 2.10.7) ===
<source lang="bash">com.openexchange.smime.checkCRL</source>
Enables or disables checking certificate revocation lists when verifying certificates

<source lang="bash">com.openexchange.smime.caGroupId</source>
Specifies a certificate authority group number to which the user belongs. All users withing that group will trust certificate authorities configured for that group.

=== Autocrypt (as of 2.10.2) ===
<source lang="bash">com.openexchange.guard.autoCryptEnabled</source>
Enables AutoCrypt functionality for Guard. If incoming emails have an AutoCrypt header, the key will be imported. Outgoing emails contain the users public key in an autocrypt header.

<source lang="bash">com.openexchange.guard.autoCryptMutual</source>
On outgoing AutoCrypt headers, specifies desired AutoCrypt mode

=== Email ===

<source lang="bash">com.openexchange.guard.guestSMTPServer=smtp.example.com
com.openexchange.guard.guestSMTPPort=25
com.openexchange.guard.guestSMTPUsername=
com.openexchange.guard.guestSMTPPassword=</source>
SMTP settings for outgoing emails from the guest reader. Emails sent from within the system use the OX Backend. The guest reader, however, sends replies through this SMTP. In addition, password emails (reset, initial) are sent through the SMTP server.

=== Bad Attempts ===

<source lang="bash">com.openexchange.guard.badMinuteLock = 10</source>
Defines how long someone will be locked out after bad attempts. Defaults to 10 minutes.

<source lang="bash">com.openexchange.guard.badPasswordCount = 5</source>
Defines how many times a person can attempt to unlock an encrypted item before being locked out. Defaults to 5 times.

=== RSA Key Generation for PGP keys ===

<source lang="bash">com.openexchange.guard.rsacache = true</source>
RSA keys are pre-generated in the background, encrypted, and stored for future user keys. RSA key generation is the most time consuming function and the RSA cache significantly improves new user creation time.

<source lang="bash">com.openexchange.guard.rsacachecount = 100</source>
Number of RSA keys to pre-generate

<source lang="bash">com.openexchange.guard.keycachecheckinterval = 30</source>
Interval in seconds to check the RSA cache and re-populate if less than rsacachecount.

<source lang="bash">com.openexchange.guard.rsacertainty = 256</source>
Bit certainty for RSA key generation. Higher numbers assure the number is in fact prime but time consuming. Lower is much faster. May need to be lower if not using cache.

=== Passwords ===

<source lang="bash">com.openexchange.guard.newpasslength=8</source>
Length of the randomly generated passwords when a user resets password.

<source lang="bash">com.openexchange.guard.minpasswordlength=6</source>
Minimum password length.

=== Backend ===

<source lang="bash">com.openexchange.guard.oxbackendpath = /ajax/</source>
URL used to communicated directly with the OX backend.

<source lang="bash">com.openexchange.guard.oxbackendidletime = 60</source>
HTTP connections to the backend are kept open for faster response. This is the timeout setting that will close idle connections.

=== Guest Accounts ===

<source lang="bash">com.openexchange.guard.shardsize=1000</source>
Guest users data are placed in databases oxguard_x. After set number of users, another database shard is created

<source lang="bash">com.openexchange.guard.guestCleanedAfterDaysOfInactivity=365</source>
Specifies how long emails and guest accounts are maintained for guests that have not had any
activity. If the guest has not logged into the Guest account in the configured time, the
emails are removed and the Guest account is closed.
0 implies indefinite (no cleaning done). Default 365 days

=== Recovery ===

If you do not want password recovery available, you can disable by adding

<source lang="bash">com.openexchange.guard.noRecovery = true</source>
Keep in mind, that a lost password will result in total loss of encrypted data.

=== Miscellaneous ===

<source lang="bash">com.openexchange.guard.secureReply = true</source>
(since Guard 2.2) Normally, when a person replies from an encrypted email, the reply is automatically encrypted. Set to false to disable this automatic encryption

== SSL ==

Starting with 2.4.0, OX Guard is running inside the OSGi container, meaning that all its servlets are being registered and served by Grizzly.

=== API SSL ===

<source lang="bash">com.openexchange.guard.backendSSL = false</source>
Per default the connection between the Guard backend and the configured Open-Xchange
REST API host is unencrypted. Even though that Guard will never transmit unencrypted
emails to or from the REST API you can optionally encrypt the whole communication between
those two components by using SSL. Please note: Enabling SSL might decrease performance
and/or create more system load due to additional encoding of the HTTP streams.

=== Incoming SSL ===

The communication between the frontend load balancer (Apache or otherwise) to Guard is by default HTTP (if protected network). More information on how to enable SSL you can find [http://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#X-FORWARDED-PROTO_Header here].

AppSuite:OX Guard MailFilter

2020-05-13T12:40:39Z

Greg.hill: Add guard-backend-mailfilter package info

= 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 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.

Incoming emails then go through the Sieve filter, which then calls the external script with the users 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.

== 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 ===

<pre>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
}</pre>
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

<pre>#!/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"</pre>
/usr/lib/dovecot/sieve-execute/guard-sig.sh

<pre>#!/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</pre>
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 <code>open-xchange-guard-backend-mailfilter</code> package needs to be installed. This should be on the same nodes as the <code>open-xchange-guard-backend-plugin</code> package is installed.

=== Debian ===
<pre>
apt-get install open-xchange-guard-backend-mailfilter
</pre>

=== Redhat ===
<pre>
yum install open-xchange-guard-backend-mailfilter
</pre>

=== SUSE ===
<pre>
zipper in open-xchange-guard-backend-mailfilter
</pre>

== 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.

AppSuite:OX Guard

2020-05-08T16:43:07Z

Greg.hill: Add mailfilter integration documentation

= OX Guard (Version 2.10) =

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0 | Installation and information of OX Guard 2.0 - 2.2]]
* [[Appsuite:OX_Guard_2_8 | Installation and information of OX Guard 2.4 - 2.8]]

If upgrading from 2.6 or 2.8, please see
* [[Appsuite:OX_Guard_Upgrade_2_10|Upgrading to 2.10]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|-
|7.8.4
|2.8.0
|-
|7.10.0
|2.10.0
|-
|7.10.1
|2.10.1
|-
|7.10.2
|2.10.2
|-
|7.10.3
|2.10.3
|}

=== Important Notes ===

==== Customisation ====

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 Customisation] 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:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-guard-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code> and <code>open-xchange-guard-ui</code>.

The components required for the OX frontend are: <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files).

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 8.0 (Jessie) ===

Support of Debian Jessie is deprecated. Read More: https://forum.open-xchange.com/showthread.php?11205

=== Debian Linux 9.0 (Stretch) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianStretch /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /

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 <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* ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianBuster /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBuster /

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 <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 6 or CentOS 6 ===

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/RHEL6/
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/RHEL6/
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 <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 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 <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).

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static

or the following for a distributed installation:

$ zypper ref
$ zypper in 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).

=== 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== 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 8.0 (Jessie) ===

Support of Debian Jessie is deprecated. Read More: https://forum.open-xchange.com/showthread.php?11205

=== Debian Linux 9.0 (Stretch) ===

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/DebianStretch />
deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /</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 6 or CentOS 6 ===

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/RHEL6/
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/RHEL6/
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 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>

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration_2_10 Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>

===== Debian GNU/Linux 9.0 =====

<source lang="bash">$ vim /etc/apache2/conf-enabled/proxy_http.conf</source>

<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 <code>ProxyPass /appsuite/api</code> 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

<source lang="bash">$ apachectl restart</source>

=== Open-Xchange Middleware Configuration ===

Edit the <code>guard-api.properties</code> 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 <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</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.

'''Guard Mail''' and '''Guard Drive''' 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.

Each of those two 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 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>
==== Guard Drive: ====

<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.

=== 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.
<code>/opt/open-xchange/etc/share.properties</code>
<source lang="bash">com.openexchange.share.guestCapabilityMode=static
com.openexchange.share.staticGuestCapabilities=guard</source>
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.
<source lang="bash">com.openexchange.share.transientSessions=false</source>

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.example.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

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
<source lang="bash">ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu</source>
in the proxy_http.conf as above.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>

==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>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 <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>

==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

=== Mail Filter Integration (2.10.4+) ===

To add additional mail filter tests (verify PGP signature, or encrypt incoming), please see
[[AppSuite:OX_Guard_MailFilter | 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 ===

<code>POST /guardsupport/?action=reset_password</code>

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:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (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 ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

=== Upgrade User (Release 2.10 and later) ===

<code>POST /guardsupport/?action=upgrade_guest</code>

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:

* <code>email</code> - The email address of the Guest user
* <code>user_id</code> – The user's new id
* <code>cid</code> - The user's new context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard MailFilter

2020-05-08T16:35:45Z

Greg.hill: OX Guard MailFilter Integration

= 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 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.

Incoming emails then go through the Sieve filter, which then calls the external script with the users 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.

== 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 ===

<pre>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
}</pre>
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

<pre>#!/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"</pre>
/usr/lib/dovecot/sieve-execute/guard-sig.sh

<pre>#!/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</pre>
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

== 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.

AppSuite:OX Guard Configuration 2 10

2019-09-27T18:25:17Z

Greg.hill: /* Optional Properties */

= OX Guard 2.10 Configuration =

There are two main files for configuring OX Guard: <code>guard-api.properties</code> and <code>guard-core.properties</code>. The first configuration file is part of the OX backend and contains properties, among others, that enable the OX Guard functionality for various modules such as Mail and Drive as well as some capabilities. The second configuration file is part of the OX Guard and contains properties that configures the behaviour of the product.

== Configuration File (<code>guard-api.properties</code>) ==

=== Main Properties ===

<source lang="bash">com.openexchange.capability.guard = true</source>
Enables Guard. If not set, no guard functions will be loaded in the UI. Needed if users should be able to do ANY Guard functions including reading encrypted emails. This level will allow users without "guard-mail" enabled to read emails sent to them, reply to those emails, but not create new emails. Recommended minimum level for all users.

<source lang="bash">com.openexchange.capability.guard-mail = true</source>
Enables the user(s) ability to send encrypted emails. If False but guard enabled, they can read encrypted emails and reply to the original sender, but they cannot compose new emails

<source lang="bash">com.openexchange.capability.guard-drive = true</source>
Enables the drive functionality. If false, user(s) will not be able to decode nor upload new encrypted files

=== Optional Properties ===

<source lang="bash">com.openexchange.guard.templateID = 0</source>
Define template customization ID for the Guest reader emails, the Guest reader, and system emails. See [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization Customization] for details.

<source lang="bash">com.openexchange.guard.endpoint =</source>
Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8009/guardadmin. By default is empty.

==== Capabilities ====

<source lang="bash">com.openexchange.capability.guard-nodeleterecovery = true</source>
(Guard 2.0) Disable the ability of the user to delete the recovery keys. Makes it impossible to reset password, but also adds level of protection/security

<source lang="bash">com.openexchange.capability.guard-nodeleteprivate = true</source>
(Guard 2.0) Disable the ability of the user to delete their private key. They can revoke it, but not delete the key.

<source lang="bash">com.openexchange.capability.guard-nodeleteonrevoke = true</source>
(Deprecated as of Guard 2.0) Default when revoking an item is to delete the content key, making the item impossible to decode. If this option is true, then the item is merely expired and can later be retrieved for decoding in case of legal requirements, corporate requirements, etc

<source lang="bash">com.openexchange.capability.guard-noextra = true</source>
(Deprecated as of Guard 2.0) Disables the ability to add an extra password to encrypted items. May be required by some industry

== Configuration File (<code>guard-core.properties</code>) ==

=== Database ===

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname = localhost</source>
The address of the MySQL database for OX Guard data. May be the same as the OX MySQL database.

<source lang="bash">com.openexchange.guard.oxguardDatabaseRead</source>
Optional read-only IP/name for the OX Guard database that might be used in Master-Slave setups.

<source lang="bash">com.openexchange.guard.oxguardShardDatabase</source>
IP/Name for the location of the Guest database shards. Additional shards will be created on this database

<source lang="bash">com.openexchange.guard.oxguardShardRead</source>
Optional read-only IP/name for Guest database shards that might be used in Master-Slave setups.

<source lang="bash">com.openexchange.guard.databaseUsername = username</source>
The username to access the OX Backend and Guard database. This user needs to have select, create, lock, insert, update privileges. Guard database user also should have alter (for updates), drop, index.

<source lang="bash">com.openexchange.guard.databasePassword = password</source>
The password for the databases

=== OX API ===

<source lang="bash">com.openexchange.guard.restApiHostname = localhost</source>
The address for the OX REST API. It would be the location of the OX Backend

<source lang="bash">com.openexchange.guard.OXBackendPort = 8009</source>
The port for the OX Backend. Default is 8009 (which is direct communication with the backend). Could be 80, etc, if going through load balancers

<source lang="bash">com.openexchange.guard.restApiUsername = open-xchange com.openexchange.guard.restApiPassword = secret</source>
Username and password for the REST API

<source lang="bash">com.openexchange.guard.externalEmailURL = example.com/appsuite/api/oxguard/reader/reader.html</source>
When Guard sends an encrypted eMail to members, they may not be using the webmail UI to read the email. A help file is attached, and a link will be provided to log into their webmail to read the encrypted item. This setting is used to point to a generic log in for the webmail system. Sent to multiple recipients, so not customized to the individual recipient.

=== Support API ===

<source lang="bash">com.openexchange.guard.supportapiusername = xxxxx
com.openexchange.guard.supportapipassword = yyyyy</source>
If the support API is to be used, a username and password should be configured.

<source lang="bash">com.openexchange.guard.exposedKeyDurationInHours = 168</source>
When a user is deleted, the Private keys are saved in a temporary deleted Keys table (in case of accidental deletion). If support "exposes" the key, the user can then retrieve it using link generated. For security reasons, this link is only valid for a short period of time. This property defines that duration.

=== File Storage ===

Local/remote storage is required for temporary caching of encrypted emails to guest/non-OX users. This can be an attached local file store, or Amazon S3 compatible object store depending on which <code>open-xchange-guard-*-storage</code> package is installed (<code>file</code> or <code>S3</code>).

==== General Properties ====

<source lang="bash">com.openexchange.guard.guestCleanedAfterDaysOfInactivity=365</source>
Specifies how long emails and guest accounts are maintained for guests that have not had any activity. If the guest has not logged into the Guest account in the configured time, the emails are removed and the Guest account is closed.

=== Storage Specific Properties ===

==== File-Storage ====

<source lang="bash">com.openexchange.guard.storage.file.uploadDirectory = /var/spool/open-xchange/guard/uploads</source>
Defines the temporary upload and cache directory for OX Guard Drive files for <code>open-xchange-guard-file-storage</code> package.
This directory needs to be shared between application servers serving the Guest Reader interface.

==== S3-Storage ====

<source lang="bash">com.openexchange.guard.storage.s3.endpoint =
com.openexchange.guard.storage.s3.bucketName =
com.openexchange.guard.storage.s3.region =
com.openexchange.guard.storage.s3.accessKey =
com.openexchange.guard.storage.s3.secretKey =</source>
S3 configuration options if the package <code>open-xchange-guard-s3-storage</code> is selected.

=== Crypto ===

<source lang="bash">com.openexchange.guard.aesKeyLength=256 (Depreciated)</source>
AES Key length. 256 is preferred, but not supported on all systems. May need to have the [http://www.oracle.com/technetwork/java/javase/downloads/index.html Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files] installed.

<source lang="bash">com.openexchange.guard.rsaKeyLength=2048</source>
RSA key length. Used when creating PGP keys

=== PGP ===

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
List of PGP Public key servers to query for public keys

<source lang="bash">com.openexchange.guard.publicKeyWhitelist</source>
A list of IP addresses of TRUSTED Guard servers. When the public PGP key server is queried, it will normally only find Guard keys that have already been created. If on the whitelist, the Guard server will also query the OX backend to see if the email address exists on the OX system, and if so, will create new keys for the user.

<source lang="bash">com.openexchange.guard.keyValidDays = 3650</source>
PGP keys created will only be valid for this number of days. Default is 10 years. Set to 0 if no expiration date.

<source lang="bash">com.openexchange.guard.pgpCacheDays=7</source>
When looking up remote PGP keys, if found, the keys will be stored in a temporary cache. Set number of days until the cache item is expired and remote lookup is repeated.

<pre>com.openexchange.guard.useStartTLS = true</pre>
Use TLS when delivering to the SMTP server when available

=== Autocrypt (as of 2.10.2) ===
<source lang="bash">com.openexchange.guard.autoCryptEnabled</source>
Enables AutoCrypt functionality for Guard. If incoming emails have an AutoCrypt header, the key will be imported. Outgoing emails contain the users public key in an autocrypt header.

<source lang="bash">com.openexchange.guard.autoCryptMutual</source>
On outgoing AutoCrypt headers, specifies desired AutoCrypt mode

=== Email ===

<source lang="bash">com.openexchange.guard.guestSMTPServer=smtp.example.com
com.openexchange.guard.guestSMTPPort=25
com.openexchange.guard.guestSMTPUsername=
com.openexchange.guard.guestSMTPPassword=</source>
SMTP settings for outgoing emails from the guest reader. Emails sent from within the system use the OX Backend. The guest reader, however, sends replies through this SMTP. In addition, password emails (reset, initial) are sent through the SMTP server.

=== Bad Attempts ===

<source lang="bash">com.openexchange.guard.badMinuteLock = 10</source>
Defines how long someone will be locked out after bad attempts. Defaults to 10 minutes.

<source lang="bash">com.openexchange.guard.badPasswordCount = 5</source>
Defines how many times a person can attempt to unlock an encrypted item before being locked out. Defaults to 5 times.

=== RSA Key Generation ===

<source lang="bash">com.openexchange.guard.rsacache = true</source>
RSA keys are pre-generated in the background, encrypted, and stored for future user keys. RSA key generation is the most time consuming function and the RSA cache significantly improves new user creation time.

<source lang="bash">com.openexchange.guard.rsacachecount = 100</source>
Number of RSA keys to pre-generate

<source lang="bash">com.openexchange.guard.keycachecheckinterval = 30</source>
Interval in seconds to check the RSA cache and re-populate if less than rsacachecount.

<source lang="bash">com.openexchange.guard.rsacertainty = 256</source>
Bit certainty for RSA key generation. Higher numbers assure the number is in fact prime but time consuming. Lower is much faster. May need to be lower if not using cache.

=== Passwords ===

<source lang="bash">com.openexchange.guard.newpasslength=8</source>
Length of the randomly generated passwords when a user resets password.

<source lang="bash">com.openexchange.guard.minpasswordlength=6</source>
Minimum password length.

=== Backend ===

<source lang="bash">com.openexchange.guard.oxbackendpath = /ajax/</source>
URL used to communicated directly with the OX backend.

<source lang="bash">com.openexchange.guard.oxbackendidletime = 60</source>
HTTP connections to the backend are kept open for faster response. This is the timeout setting that will close idle connections.

=== Guest Accounts ===

<source lang="bash">com.openexchange.guard.shardsize=1000</source>
Guest users data are placed in databases oxguard_x. After set number of users, another database shard is created

<source lang="bash">com.openexchange.guard.guestCleanedAfterDaysOfInactivity=365</source>
Specifies how long emails and guest accounts are maintained for guests that have not had any
activity. If the guest has not logged into the Guest account in the configured time, the
emails are removed and the Guest account is closed.
0 implies indefinite (no cleaning done). Default 365 days

=== Recovery ===

If you do not want password recovery available, you can disable by adding

<source lang="bash">com.openexchange.guard.noRecovery = true</source>
Keep in mind, that a lost password will result in total loss of encrypted data.

=== Miscellaneous ===

<source lang="bash">com.openexchange.guard.secureReply = true</source>
(since Guard 2.2) Normally, when a person replies from an encrypted email, the reply is automatically encrypted. Set to false to disable this automatic encryption

== SSL ==

Starting with 2.4.0, OX Guard is running inside the OSGi container, meaning that all its servlets are being registered and served by Grizzly.

=== API SSL ===

<source lang="bash">com.openexchange.guard.backendSSL = false</source>
Per default the connection between the Guard backend and the configured Open-Xchange
REST API host is unencrypted. Even though that Guard will never transmit unencrypted
emails to or from the REST API you can optionally encrypt the whole communication between
those two components by using SSL. Please note: Enabling SSL might decrease performance
and/or create more system load due to additional encoding of the HTTP streams.

=== Incoming SSL ===

The communication between the frontend load balancer (Apache or otherwise) to Guard is by default HTTP (if protected network). More information on how to enable SSL you can find [http://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#X-FORWARDED-PROTO_Header here].

AppSuite:OX Guard

2019-07-08T17:13:57Z

Greg.hill: /* Version Matrix */

= OX Guard (Version 2.4 - 2.8) =

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|-
|7.8.4
|2.8.0
|-
|7.10.0
|2.10.0
|-
|7.10.1
|2.10.1
|-
|7.10.2
|2.10.2
|-
|}

=== Important Notes ===

==== Customisation ====

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 Customisation] 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:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-guard-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code> and <code>open-xchange-guard-ui</code>.

The components required for the OX frontend are: <code>open-xchange-guard-ui-static</code> <code>open-xchange-guard-reader</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files).

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 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>

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 open-xchange-guard-reader</source>

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== RedHat Enterprise Linux 6 or CentOS 6 ===

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/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

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 open-xchange-guard-reader</source>
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> 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</source>

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 open-xchange-guard-reader</source>
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>

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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 11 (valid until v2.4.2) ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/2.4.2/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/7.8.2/backend/SLES11 ox-backend</source>

and then run for a single node installation:

$ zypper ref
$ zypper in 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-reader</source>

or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>

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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) (valid until v2.4.2) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.4.2/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.8.2/backend/DebianWheezy /</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 8.0 (Jessie) ===

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/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</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 6 or CentOS 6 ===

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/RHEL6/
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/RHEL6/
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 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>

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== 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.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><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</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> 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 BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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 starting the initialization. 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</code>
* Guard Documents: <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.

'''Guard Mail''', '''Guard Drive''', and '''Guard Documents''' 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. "Guard Documents" enable encryption capabilitiy to office documents.

Each of the 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 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>
==== Guard Drive: ====

<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>

==== Guard Documents: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-docs=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 bakend.

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>

==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><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
</source>

Make sure that the balancer is properly configured in the <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>

==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== 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:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportApiUsername=
com.openexchange.guard.supportApiPassword=</source>
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 ===

<code>POST /guardsupport/?action=reset_password</code>

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:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (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 ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

=== Upgrade User (Release 2.10 and later) ===

<code>POST /guardsupport/?action=upgrade_guest</code>

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:

* <code>email</code> - The email address of the Guest user
* <code>user_id</code> – The user's new id
* <code>cid</code> - The user's new context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard

2019-07-08T17:11:52Z

Greg.hill: /* Enabling Guard for Users */

= OX Guard (Version 2.4 - 2.8) =

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|-
|7.8.4
|2.8.0
|-
|7.10.0
|2.10.0
|-
|7.10.1
|2.10.1
|}

=== Important Notes ===

==== Customisation ====

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 Customisation] 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:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-guard-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code> and <code>open-xchange-guard-ui</code>.

The components required for the OX frontend are: <code>open-xchange-guard-ui-static</code> <code>open-xchange-guard-reader</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files).

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 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>

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 open-xchange-guard-reader</source>

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== RedHat Enterprise Linux 6 or CentOS 6 ===

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/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

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 open-xchange-guard-reader</source>
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> 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</source>

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 open-xchange-guard-reader</source>
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>

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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 11 (valid until v2.4.2) ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/2.4.2/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/7.8.2/backend/SLES11 ox-backend</source>

and then run for a single node installation:

$ zypper ref
$ zypper in 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-reader</source>

or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>

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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) (valid until v2.4.2) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.4.2/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.8.2/backend/DebianWheezy /</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 8.0 (Jessie) ===

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/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</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 6 or CentOS 6 ===

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/RHEL6/
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/RHEL6/
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 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>

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== 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.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><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</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> 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 BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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 starting the initialization. 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</code>
* Guard Documents: <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.

'''Guard Mail''', '''Guard Drive''', and '''Guard Documents''' 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. "Guard Documents" enable encryption capabilitiy to office documents.

Each of the 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 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>
==== Guard Drive: ====

<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>

==== Guard Documents: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-docs=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 bakend.

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>

==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><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
</source>

Make sure that the balancer is properly configured in the <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>

==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== 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:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportApiUsername=
com.openexchange.guard.supportApiPassword=</source>
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 ===

<code>POST /guardsupport/?action=reset_password</code>

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:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (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 ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

=== Upgrade User (Release 2.10 and later) ===

<code>POST /guardsupport/?action=upgrade_guest</code>

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:

* <code>email</code> - The email address of the Guest user
* <code>user_id</code> – The user's new id
* <code>cid</code> - The user's new context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:GuardConfiguration

2019-07-08T15:50:40Z

Greg.hill: /* Recovery */

= Cascade Options =

== Main Options ==

'''com.openexchange.capability.guard=true'''

Enables Guard. If not set, no guard functions will be loaded in the UI. Needed if users should be able to do ANY Guard functions including reading encrypted emails. This level will allow users without "guard-mail" enabled to read emails sent to them, reply to those emails, but not create new emails. Recommended minimum level for all users.

'''com.openexchange.capability.guard-mail=true'''

Enables the user(s) ability to send encrypted emails. If False but guard enabled, they can read encrypted emails and reply to the original sender, but they cannot compose new emails

'''com.openexchange.capability.guard-drive=true'''

Enables the drive functionality. If false, user(s) will not be able to decode nor upload new encrypted files

== Optional Cascade Options ==

=== Capabilities ===

'''com.openexchange.capability.guard-pin'''

Enables optional PIN function when sending emails to non-ox users. Will provide an additional 4 digit pin that should be sent to the recipient. Extra protection during the time that the temporary password was assigned and sent.

'''com.openexchange.capability.guard-nodeleterecovery'''

(Guard 2.0) Disable the ability of the user to delete the recovery keys. Makes it impossible to reset password, but also adds level of protection/security

'''com.openexchange.capability.guard-norecovery'''

(Guard 2.0) Password recovery is disabled. No way to recover a lost or forgotten password. Increases security, but a lost password means lost data.

'''com.openexchange.capability.guard-nodeleteprivate'''

(Guard 2.0) Disable the ability of the user to delete their private key. They can revoke it, but not delete the key.

'''com.openexchange.guard.secureReply'''

(Guard 2.2) Normally, when a person replies from an encrypted email, the reply is automatically encrypted. Set to false to disable this automatic encryption

'''com.openexchange.capability.guard-nodeleteonrevoke''' (Depreciated as of Guard 2.0)

Default when revoking an item is to delete the content key, making the item impossible to decode. If this option is true, then the item is merely expired and can later be retrieved for decoding in case of legal requirements, corporate requirements, etc

'''com.openexchange.capability.guard-noextra''' (Depreciated as of Guard 2.0)

Disables the ability to add an extra password to encrypted items. May be required by some industry

=== Configuration Variables ===

'''com.openexchange.guard.fromEmail= name<email>'''

Email address to use as the From address when sending automated emails (First password, password reset)

'''com.openexchange.guard.externalReaderURL'''

When sending an email to a guest, this URL is used for the link to the Guest reader

'''com.openexchange.guard.externalOxUI'''

PGP MIME emails are sent with a help file attached. This is the URL to the main appsuite UI that is included in the help file

'''com.openexchange.guard.templateID'''

Define template customization ID for the Guest reader emails, the Guest reader, and system emails. See [[AppSuite:GuardCustomization|Customization]] for details

== Configuration file (guard.properties) ==

=== Database ===

'''com.openexchange.guard.configdbHostname=localhost'''

The address of the mysql database that contains the OX Backend configdb. This is used during initial setup and database sharding

'''com.openexchange.guard.oxguardDatabaseHostname=localhost'''

The address of the mysql database for OxGuard data. May be the same as the OX mysql database

'''com.openexchange.guard.oxguardDatabaseRead'''

Optional read-only IP/name for the Guard database.

'''com.openexchange.guard.oxguardShardDatabase'''

IP/Name for the location of the next Guest database shard. Additional shards will be created on this database

'''com.openexchange.guard.databaseUsername=username'''

The username to access the OX Backend and Guard database. This user needs to have select, create, lock, insert, update privileges. Guard database user also should have alter (for updates), drop, index

'''com.openexchange.guard.databasePassword=password'''

The password for the databases

=== OX API ===

'''com.openexchange.guard.restApiHostname=localhost'''

The address for the OX REST API. It would be the location of the OX Backend

'''com.openexchange.guard.OXBackendPort = 8009'''

The port for the OX Backend. Default is 8009 (which is direct communication with the backend). Could be 80, etc, if going through load balancers

'''com.openexchange.guard.restApiUsername=open-xchange'''
'''com.openexchange.guard.restApiPassword=secret'''

Username and password for the REST API

'''com.openexchange.guard.externalEmailURL=example.com'''

=== Support API ===

If the support API is to be used, a username and password should be configured

'''com.openexchange.guard.supportapiusername=xxxxx'''

'''com.openexchange.guard.supportapipassword=yyyyy'''

When a user is deleted, the Private keys are saved in a temporary deleted Keys table (in case of accidental deletion). If support "exposes" the key, the user can then retrieve it using link generated. For security reasons, this link is only valid for a short period of time.

'''com.openexchange.guard.exposedKeyDurationInHours=168'''

=== File Store ===

When non-ox users get an email with a link to read the message, an external url is required so they can visit the non-ox reader page. This should be the public domain that would prefix /appsuite/api/guard/reader

'''com.openexchange.guard.storage.type=file'''

Local/remote storage is required for temporary caching of non-ox encrypted emails. This can be an attached file store, or Amazon S3 compatible object store. Values are “file” or “s3”

'''com.openexchange.guard.storage.file.uploadDirectory=/var/spool/open-xchange/guard/uploads'''

Location of local filestore if type was “file”

'''com.openexchange.guard.storage.s3.endpoint='''

'''com.openexchange.guard.storage.s3.bucketName='''

'''com.openexchange.guard.storage.s3.region='''

'''com.openexchange.guard.storage.s3.accessKey='''

'''com.openexchange.guard.storage.s3.secretKey='''

S3 configuration options if filestore selected was S3

'''com.openexchange.guard.cacheDays=30'''

How many days emails are kept in file store before being deleted. Measured from time of sending, reset when someone reads the email

'''com.openexchange.guard.cronHour=2'''

Time that the filestore is checked for old items

=== Crypto ===

'''com.openexchange.guard.aesKeyLength=256''' (Depreciated)

AES Key length. 256 is preferred, but not supported on all systems. May need to have java unlimeted key strength pack installed

'''com.openexchange.guard.rsaKeyLength=2048'''

RSA key length. Used when creating PGP keys

'''com.openexchange.guard.keyValidDays=3650'''

Length of time for PGP key validity. Set to 0 if no expiration date

=== PGP ===

'''com.openexchange.guard.publicPGPDirectory'''

List of PGP Public key servers to query for public keys

'''com.openexchange.guard.publicKeyWhitelist'''

A list of IP addresses of TRUSTED Guard servers. When the public PGP key server is queried, it will normally only find Guard keys that have already been created. If on the whitelist, the Guard server will also query the OX backend to see if the email address exists on the OX system, and if so, will create new keys for the user

'''com.openexchange.guard.keyValidDays'''

PGP keys created will only be valid for this number of days. Default is 10 years

=== Email ===

'''com.openexchange.guard.guestSMTPServer=smtp.example.com'''

'''com.openexchange.guard.guestSMTPPort=25'''

'''com.openexchange.guard.guestSMTPUsername='''

'''com.openexchange.guard.guestSMTPPassword='''

SMTP settings for outgoing emails from the guest reader. Emails sent from within the system use the OX Backend. The guest reader, however, sends replies through this SMTP. In addition, password emails (reset, initial) are sent through the SMTP server

=== Remote ===

'''com.openexchange.guard.pgpCacheDays=7

When looking up remote PGP keys, if found, the keys will be stored in a temporary cache. Set number of days until the cache item is expired and remote lookup is repeated.

Optional

'''com.openexchange.guard.usestarttls = true'''

Use TLS when delivering to the SMTP server when available

=== Bad attempts ===

'''com.openexchange.guard.badMinuteLock= 10'''

Defines how long someone will be locked out after bad attempts. Default 10

'''com.openexchange.guard.badPasswordCount= 5'''

Defines how many times a person can attempt to unlock an encrypted item before being locked out. Default 5

'''com.openexchange.guard.badIpCount: 10'''

Defines how many times an outside computer can request a public key that doesn't exist before being locked out

=== RSA Key Generation ===

'''com.openexchange.guard.rsacache=true'''

RSA keys are pre-generated in the background, encrypted, and stored for future user keys. RSA key generation is the most time consuming function and the RSA cache significantly improves new user creation time

'''com.openexchange.guard.rsacachecount=100'''

Number of RSA keys to pre-generate

'''com.openexchange.guard.keycachecheckinterval= 30'''

Interval in seconds to check the RSA cache and re-populate if less than rsacachecount

'''com.openexchange.guard.rsacertainty=256'''

Bit certainty for RSA key generation. Higher numbers assure the number is in fact prime but time consuming. Lower is much faster. May need to be lower if not using cache

=== Passwords ===

'''com.openexchange.guard.newpasslength=8'''

Length of the randomly generated passwords when a user resets password.

'''com.openexchange.guard.minpasswordlength=6'''

Minimum password length

=== Backend ===

'''com.openexchange.guard.oxbackendpath=/ajax/'''

URL used to communicated directly with the OX backend

'''com.openexchange.guard.oxbackendidletime=60'''

HTTP connections to the backend are kept open for faster response. This is the timeout setting that will close idle connections.

'''com.openexchange.guard.configdbname=configdb'''

Name of the configdb database

=== Support ===

'''com.openexchange.guard.supportApiUsername'''

Username for the support API

'''com.openexchange.guard.supportApiPassword'''

Password for the support API

=== Guest Accounts ===

'''com.openexchange.guard.shardsize=1000'''

Guest users data are placed in databases oxguard_x. After set number of users, another database shard is created

'''com.openexchange.guard.externalreaderpath=/appsuite/api/oxguard/reader/reader.html'''

Full path after domain name for the external reader (if changed from default)

==Optional Configuration Settings==

=== API SSL ===

'''com.openexchange.guard.backend_ssl=true'''

Communication between Guard and the OX backend is set to HTTP by default. All items to be encrypted are already encrypted at this point, but other information (sender name, filename, etc) could appear in plaintext here. If SSL is desired, sest to true.

=== Incoming SSL ===

Communication between the frontend load balancer (APACHE or otherwise) to Guard is by default HTTP (if protected network). To have Guard listen on an SSL socket, the following needs to be set

'''com.openexchange.guard.useSSL= true'''

Enables jetty listener for ssl

'''com.openexchange.guard.SSLPort= 8443'''

Jetty will listen on defined port for ssl connections

'''com.openexchange.guard.SSLKeyStore= xxxx'''

Location of the keystore with ssl keys

'''com.openexchange.guard.SSLKeyName= xxxx'''

Name/alieas of the key to use

'''com.openexchange.guard.SSLKeyPass= xxxx'''

Password for the ssl key

=== Recovery ===

If you do not want password recovery available, you can disable by adding

'''com.openexchange.guard.noRecovery= true'''

Keep in mind, that a lost password will result in total loss of encrypted data

Users will be able to change their passwords if they remember their current/old password. But they won't be able to create a new password in the event it is forgotten.

Users without recovery would have to create new keys, with a new password, to continue to use Guard. These keys would apply to future encrypted items, not the old ones.

Guests that forget their passwords will need to have their account reset from the command line tool (this will create new keys for them, and send them a new password)

=== Misc ===

'''com.openexchange.guard.defaultlanguage=en_US'''

Default language if a language is requested but not available

AppSuite:OX Guard Configuration 2 10

2019-03-21T17:01:52Z

Greg.hill: /* PGP */

= OX Guard 2.10 Configuration =

There are two main files for configuring OX Guard: <code>guard-api.properties</code> and <code>guard-core.properties</code>. The first configuration file is part of the OX backend and contains properties, among others, that enable the OX Guard functionality for various modules such as Mail and Drive as well as some capabilities. The second configuration file is part of the OX Guard and contains properties that configures the behaviour of the product.

== Configuration File (<code>guard-api.properties</code>) ==

=== Main Properties ===

<source lang="bash">com.openexchange.capability.guard = true</source>
Enables Guard. If not set, no guard functions will be loaded in the UI. Needed if users should be able to do ANY Guard functions including reading encrypted emails. This level will allow users without "guard-mail" enabled to read emails sent to them, reply to those emails, but not create new emails. Recommended minimum level for all users.

<source lang="bash">com.openexchange.capability.guard-mail = true</source>
Enables the user(s) ability to send encrypted emails. If False but guard enabled, they can read encrypted emails and reply to the original sender, but they cannot compose new emails

<source lang="bash">com.openexchange.capability.guard-drive = true</source>
Enables the drive functionality. If false, user(s) will not be able to decode nor upload new encrypted files

=== Optional Properties ===

<source lang="bash">com.openexchange.guard.templateID = 0</source>
Define template customization ID for the Guest reader emails, the Guest reader, and system emails. See [https://oxpedia.org/wiki/index.php?title%20=%20AppSuite:GuardCustomization Customization] for details.

<source lang="bash">com.openexchange.guard.endpoint =</source>
Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8009/guardadmin. By default is empty.

==== Capabilities ====

<source lang="bash">com.openexchange.capability.guard-nodeleterecovery = true</source>
(Guard 2.0) Disable the ability of the user to delete the recovery keys. Makes it impossible to reset password, but also adds level of protection/security

<source lang="bash">com.openexchange.capability.guard-nodeleteprivate = true</source>
(Guard 2.0) Disable the ability of the user to delete their private key. They can revoke it, but not delete the key.

<source lang="bash">com.openexchange.capability.guard-nodeleteonrevoke = true</source>
(Deprecated as of Guard 2.0) Default when revoking an item is to delete the content key, making the item impossible to decode. If this option is true, then the item is merely expired and can later be retrieved for decoding in case of legal requirements, corporate requirements, etc

<source lang="bash">com.openexchange.capability.guard-noextra = true</source>
(Deprecated as of Guard 2.0) Disables the ability to add an extra password to encrypted items. May be required by some industry

== Configuration File (<code>guard-core.properties</code>) ==

=== Database ===

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname = localhost</source>
The address of the MySQL database for OX Guard data. May be the same as the OX MySQL database.

<source lang="bash">com.openexchange.guard.oxguardDatabaseRead</source>
Optional read-only IP/name for the OX Guard database that might be used in Master-Slave setups.

<source lang="bash">com.openexchange.guard.oxguardShardDatabase</source>
IP/Name for the location of the Guest database shards. Additional shards will be created on this database

<source lang="bash">com.openexchange.guard.oxguardShardRead</source>
Optional read-only IP/name for Guest database shards that might be used in Master-Slave setups.

<source lang="bash">com.openexchange.guard.databaseUsername = username</source>
The username to access the OX Backend and Guard database. This user needs to have select, create, lock, insert, update privileges. Guard database user also should have alter (for updates), drop, index.

<source lang="bash">com.openexchange.guard.databasePassword = password</source>
The password for the databases

=== OX API ===

<source lang="bash">com.openexchange.guard.restApiHostname = localhost</source>
The address for the OX REST API. It would be the location of the OX Backend

<source lang="bash">com.openexchange.guard.OXBackendPort = 8009</source>
The port for the OX Backend. Default is 8009 (which is direct communication with the backend). Could be 80, etc, if going through load balancers

<source lang="bash">com.openexchange.guard.restApiUsername = open-xchange com.openexchange.guard.restApiPassword = secret</source>
Username and password for the REST API

<source lang="bash">com.openexchange.guard.externalEmailURL = example.com/appsuite/api/oxguard/reader/reader.html</source>
When Guard sends an encrypted eMail to members, they may not be using the webmail UI to read the email. A help file is attached, and a link will be provided to log into their webmail to read the encrypted item. This setting is used to point to a generic log in for the webmail system. Sent to multiple recipients, so not customized to the individual recipient.

=== Support API ===

<source lang="bash">com.openexchange.guard.supportapiusername = xxxxx
com.openexchange.guard.supportapipassword = yyyyy</source>
If the support API is to be used, a username and password should be configured.

<source lang="bash">com.openexchange.guard.exposedKeyDurationInHours = 168</source>
When a user is deleted, the Private keys are saved in a temporary deleted Keys table (in case of accidental deletion). If support "exposes" the key, the user can then retrieve it using link generated. For security reasons, this link is only valid for a short period of time. This property defines that duration.

=== File Storage ===

Local/remote storage is required for temporary caching of encrypted emails to guest/non-OX users. This can be an attached local file store, or Amazon S3 compatible object store depending on which <code>open-xchange-guard-*-storage</code> package is installed (<code>file</code> or <code>S3</code>).

==== General Properties ====

<source lang="bash">com.openexchange.guard.guestCleanedAfterDaysOfInactivity=365</source>
Specifies how long emails and guest accounts are maintained for guests that have not had any activity. If the guest has not logged into the Guest account in the configured time, the emails are removed and the Guest account is closed.

=== Storage Specific Properties ===

==== File-Storage ====

<source lang="bash">com.openexchange.guard.storage.file.uploadDirectory = /var/spool/open-xchange/guard/uploads</source>
Defines the temporary upload and cache directory for OX Guard Drive files for <code>open-xchange-guard-file-storage</code> package.
This directory needs to be shared between application servers serving the Guest Reader interface.

==== S3-Storage ====

<source lang="bash">com.openexchange.guard.storage.s3.endpoint =
com.openexchange.guard.storage.s3.bucketName =
com.openexchange.guard.storage.s3.region =
com.openexchange.guard.storage.s3.accessKey =
com.openexchange.guard.storage.s3.secretKey =</source>
S3 configuration options if the package <code>open-xchange-guard-s3-storage</code> is selected.

=== Crypto ===

<source lang="bash">com.openexchange.guard.aesKeyLength=256 (Depreciated)</source>
AES Key length. 256 is preferred, but not supported on all systems. May need to have the [http://www.oracle.com/technetwork/java/javase/downloads/index.html Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files] installed.

<source lang="bash">com.openexchange.guard.rsaKeyLength=2048</source>
RSA key length. Used when creating PGP keys

=== PGP ===

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
List of PGP Public key servers to query for public keys

<source lang="bash">com.openexchange.guard.publicKeyWhitelist</source>
A list of IP addresses of TRUSTED Guard servers. When the public PGP key server is queried, it will normally only find Guard keys that have already been created. If on the whitelist, the Guard server will also query the OX backend to see if the email address exists on the OX system, and if so, will create new keys for the user.

<source lang="bash">com.openexchange.guard.keyValidDays = 3650</source>
PGP keys created will only be valid for this number of days. Default is 10 years. Set to 0 if no expiration date.

<source lang="bash">com.openexchange.guard.pgpCacheDays=7</source>
When looking up remote PGP keys, if found, the keys will be stored in a temporary cache. Set number of days until the cache item is expired and remote lookup is repeated.

<pre>com.openexchange.guard.useStartTLS = true</pre>
Use TLS when delivering to the SMTP server when available

=== Autocrypt (as of 2.10.2) ===
<source lang="bash">com.openexchange.guard.autoCryptEnabled</source>
Enables AutoCrypt functionality for Guard. If incoming emails have an AutoCrypt header, the key will be imported. Outgoing emails contain the users public key in an autocrypt header.

<source lang="bash">com.openexchange.guard.autoCryptMutual</source>
On outgoing AutoCrypt headers, specifies desired AutoCrypt mode

=== Email ===

<source lang="bash">com.openexchange.guard.guestSMTPServer=smtp.example.com
com.openexchange.guard.guestSMTPPort=25
com.openexchange.guard.guestSMTPUsername=
com.openexchange.guard.guestSMTPPassword=</source>
SMTP settings for outgoing emails from the guest reader. Emails sent from within the system use the OX Backend. The guest reader, however, sends replies through this SMTP. In addition, password emails (reset, initial) are sent through the SMTP server.

=== Bad Attempts ===

<source lang="bash">com.openexchange.guard.badMinuteLock = 10</source>
Defines how long someone will be locked out after bad attempts. Defaults to 10 minutes.

<source lang="bash">com.openexchange.guard.badPasswordCount = 5</source>
Defines how many times a person can attempt to unlock an encrypted item before being locked out. Defaults to 5 times.

=== RSA Key Generation ===

<source lang="bash">com.openexchange.guard.rsacache = true</source>
RSA keys are pre-generated in the background, encrypted, and stored for future user keys. RSA key generation is the most time consuming function and the RSA cache significantly improves new user creation time.

<source lang="bash">com.openexchange.guard.rsacachecount = 100</source>
Number of RSA keys to pre-generate

<source lang="bash">com.openexchange.guard.keycachecheckinterval = 30</source>
Interval in seconds to check the RSA cache and re-populate if less than rsacachecount.

<source lang="bash">com.openexchange.guard.rsacertainty = 256</source>
Bit certainty for RSA key generation. Higher numbers assure the number is in fact prime but time consuming. Lower is much faster. May need to be lower if not using cache.

=== Passwords ===

<source lang="bash">com.openexchange.guard.newpasslength=8</source>
Length of the randomly generated passwords when a user resets password.

<source lang="bash">com.openexchange.guard.minpasswordlength=6</source>
Minimum password length.

=== Backend ===

<source lang="bash">com.openexchange.guard.oxbackendpath = /ajax/</source>
URL used to communicated directly with the OX backend.

<source lang="bash">com.openexchange.guard.oxbackendidletime = 60</source>
HTTP connections to the backend are kept open for faster response. This is the timeout setting that will close idle connections.

=== Guest Accounts ===

<source lang="bash">com.openexchange.guard.shardsize=1000</source>
Guest users data are placed in databases oxguard_x. After set number of users, another database shard is created

<source lang="bash">com.openexchange.guard.guestCleanedAfterDaysOfInactivity=365</source>
Specifies how long emails and guest accounts are maintained for guests that have not had any
activity. If the guest has not logged into the Guest account in the configured time, the
emails are removed and the Guest account is closed.
0 implies indefinite (no cleaning done). Default 365 days

=== Recovery ===

If you do not want password recovery available, you can disable by adding

<source lang="bash">com.openexchange.guard.noRecovery = true</source>
Keep in mind, that a lost password will result in total loss of encrypted data.

=== Miscellaneous ===

<source lang="bash">com.openexchange.guard.secureReply = true</source>
(since Guard 2.2) Normally, when a person replies from an encrypted email, the reply is automatically encrypted. Set to false to disable this automatic encryption

== SSL ==

Starting with 2.4.0, OX Guard is running inside the OSGi container, meaning that all its servlets are being registered and served by Grizzly.

=== API SSL ===

<source lang="bash">com.openexchange.guard.backendSSL = false</source>
Per default the connection between the Guard backend and the configured Open-Xchange
REST API host is unencrypted. Even though that Guard will never transmit unencrypted
emails to or from the REST API you can optionally encrypt the whole communication between
those two components by using SSL. Please note: Enabling SSL might decrease performance
and/or create more system load due to additional encoding of the HTTP streams.

=== Incoming SSL ===

The communication between the frontend load balancer (Apache or otherwise) to Guard is by default HTTP (if protected network). More information on how to enable SSL you can find [http://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#X-FORWARDED-PROTO_Header here].

AppSuite:OX Guard Configuration 2 10

2019-03-21T16:54:37Z

Greg.hill: /* Guest Accounts */

= OX Guard 2.10 Configuration =

There are two main files for configuring OX Guard: <code>guard-api.properties</code> and <code>guard-core.properties</code>. The first configuration file is part of the OX backend and contains properties, among others, that enable the OX Guard functionality for various modules such as Mail and Drive as well as some capabilities. The second configuration file is part of the OX Guard and contains properties that configures the behaviour of the product.

== Configuration File (<code>guard-api.properties</code>) ==

=== Main Properties ===

<source lang="bash">com.openexchange.capability.guard = true</source>
Enables Guard. If not set, no guard functions will be loaded in the UI. Needed if users should be able to do ANY Guard functions including reading encrypted emails. This level will allow users without "guard-mail" enabled to read emails sent to them, reply to those emails, but not create new emails. Recommended minimum level for all users.

<source lang="bash">com.openexchange.capability.guard-mail = true</source>
Enables the user(s) ability to send encrypted emails. If False but guard enabled, they can read encrypted emails and reply to the original sender, but they cannot compose new emails

<source lang="bash">com.openexchange.capability.guard-drive = true</source>
Enables the drive functionality. If false, user(s) will not be able to decode nor upload new encrypted files

=== Optional Properties ===

<source lang="bash">com.openexchange.guard.templateID = 0</source>
Define template customization ID for the Guest reader emails, the Guest reader, and system emails. See [https://oxpedia.org/wiki/index.php?title%20=%20AppSuite:GuardCustomization Customization] for details.

<source lang="bash">com.openexchange.guard.endpoint =</source>
Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8009/guardadmin. By default is empty.

==== Capabilities ====

<source lang="bash">com.openexchange.capability.guard-nodeleterecovery = true</source>
(Guard 2.0) Disable the ability of the user to delete the recovery keys. Makes it impossible to reset password, but also adds level of protection/security

<source lang="bash">com.openexchange.capability.guard-nodeleteprivate = true</source>
(Guard 2.0) Disable the ability of the user to delete their private key. They can revoke it, but not delete the key.

<source lang="bash">com.openexchange.capability.guard-nodeleteonrevoke = true</source>
(Deprecated as of Guard 2.0) Default when revoking an item is to delete the content key, making the item impossible to decode. If this option is true, then the item is merely expired and can later be retrieved for decoding in case of legal requirements, corporate requirements, etc

<source lang="bash">com.openexchange.capability.guard-noextra = true</source>
(Deprecated as of Guard 2.0) Disables the ability to add an extra password to encrypted items. May be required by some industry

== Configuration File (<code>guard-core.properties</code>) ==

=== Database ===

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname = localhost</source>
The address of the MySQL database for OX Guard data. May be the same as the OX MySQL database.

<source lang="bash">com.openexchange.guard.oxguardDatabaseRead</source>
Optional read-only IP/name for the OX Guard database that might be used in Master-Slave setups.

<source lang="bash">com.openexchange.guard.oxguardShardDatabase</source>
IP/Name for the location of the Guest database shards. Additional shards will be created on this database

<source lang="bash">com.openexchange.guard.oxguardShardRead</source>
Optional read-only IP/name for Guest database shards that might be used in Master-Slave setups.

<source lang="bash">com.openexchange.guard.databaseUsername = username</source>
The username to access the OX Backend and Guard database. This user needs to have select, create, lock, insert, update privileges. Guard database user also should have alter (for updates), drop, index.

<source lang="bash">com.openexchange.guard.databasePassword = password</source>
The password for the databases

=== OX API ===

<source lang="bash">com.openexchange.guard.restApiHostname = localhost</source>
The address for the OX REST API. It would be the location of the OX Backend

<source lang="bash">com.openexchange.guard.OXBackendPort = 8009</source>
The port for the OX Backend. Default is 8009 (which is direct communication with the backend). Could be 80, etc, if going through load balancers

<source lang="bash">com.openexchange.guard.restApiUsername = open-xchange com.openexchange.guard.restApiPassword = secret</source>
Username and password for the REST API

<source lang="bash">com.openexchange.guard.externalEmailURL = example.com/appsuite/api/oxguard/reader/reader.html</source>
When Guard sends an encrypted eMail to members, they may not be using the webmail UI to read the email. A help file is attached, and a link will be provided to log into their webmail to read the encrypted item. This setting is used to point to a generic log in for the webmail system. Sent to multiple recipients, so not customized to the individual recipient.

=== Support API ===

<source lang="bash">com.openexchange.guard.supportapiusername = xxxxx
com.openexchange.guard.supportapipassword = yyyyy</source>
If the support API is to be used, a username and password should be configured.

<source lang="bash">com.openexchange.guard.exposedKeyDurationInHours = 168</source>
When a user is deleted, the Private keys are saved in a temporary deleted Keys table (in case of accidental deletion). If support "exposes" the key, the user can then retrieve it using link generated. For security reasons, this link is only valid for a short period of time. This property defines that duration.

=== File Storage ===

Local/remote storage is required for temporary caching of encrypted emails to guest/non-OX users. This can be an attached local file store, or Amazon S3 compatible object store depending on which <code>open-xchange-guard-*-storage</code> package is installed (<code>file</code> or <code>S3</code>).

==== General Properties ====

<source lang="bash">com.openexchange.guard.guestCleanedAfterDaysOfInactivity=365</source>
Specifies how long emails and guest accounts are maintained for guests that have not had any activity. If the guest has not logged into the Guest account in the configured time, the emails are removed and the Guest account is closed.

=== Storage Specific Properties ===

==== File-Storage ====

<source lang="bash">com.openexchange.guard.storage.file.uploadDirectory = /var/spool/open-xchange/guard/uploads</source>
Defines the temporary upload and cache directory for OX Guard Drive files for <code>open-xchange-guard-file-storage</code> package.
This directory needs to be shared between application servers serving the Guest Reader interface.

==== S3-Storage ====

<source lang="bash">com.openexchange.guard.storage.s3.endpoint =
com.openexchange.guard.storage.s3.bucketName =
com.openexchange.guard.storage.s3.region =
com.openexchange.guard.storage.s3.accessKey =
com.openexchange.guard.storage.s3.secretKey =</source>
S3 configuration options if the package <code>open-xchange-guard-s3-storage</code> is selected.

=== Crypto ===

<source lang="bash">com.openexchange.guard.aesKeyLength=256 (Depreciated)</source>
AES Key length. 256 is preferred, but not supported on all systems. May need to have the [http://www.oracle.com/technetwork/java/javase/downloads/index.html Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files] installed.

<source lang="bash">com.openexchange.guard.rsaKeyLength=2048</source>
RSA key length. Used when creating PGP keys

=== PGP ===

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
List of PGP Public key servers to query for public keys

<source lang="bash">com.openexchange.guard.publicKeyWhitelist</source>
A list of IP addresses of TRUSTED Guard servers. When the public PGP key server is queried, it will normally only find Guard keys that have already been created. If on the whitelist, the Guard server will also query the OX backend to see if the email address exists on the OX system, and if so, will create new keys for the user.

<source lang="bash">com.openexchange.guard.keyValidDays = 3650</source>
PGP keys created will only be valid for this number of days. Default is 10 years. Set to 0 if no expiration date.

<source lang="bash">com.openexchange.guard.pgpCacheDays=7</source>
When looking up remote PGP keys, if found, the keys will be stored in a temporary cache. Set number of days until the cache item is expired and remote lookup is repeated.

<pre>com.openexchange.guard.useStartTLS = true</pre>
Use TLS when delivering to the SMTP server when available

=== Email ===

<source lang="bash">com.openexchange.guard.guestSMTPServer=smtp.example.com
com.openexchange.guard.guestSMTPPort=25
com.openexchange.guard.guestSMTPUsername=
com.openexchange.guard.guestSMTPPassword=</source>
SMTP settings for outgoing emails from the guest reader. Emails sent from within the system use the OX Backend. The guest reader, however, sends replies through this SMTP. In addition, password emails (reset, initial) are sent through the SMTP server.

=== Bad Attempts ===

<source lang="bash">com.openexchange.guard.badMinuteLock = 10</source>
Defines how long someone will be locked out after bad attempts. Defaults to 10 minutes.

<source lang="bash">com.openexchange.guard.badPasswordCount = 5</source>
Defines how many times a person can attempt to unlock an encrypted item before being locked out. Defaults to 5 times.

=== RSA Key Generation ===

<source lang="bash">com.openexchange.guard.rsacache = true</source>
RSA keys are pre-generated in the background, encrypted, and stored for future user keys. RSA key generation is the most time consuming function and the RSA cache significantly improves new user creation time.

<source lang="bash">com.openexchange.guard.rsacachecount = 100</source>
Number of RSA keys to pre-generate

<source lang="bash">com.openexchange.guard.keycachecheckinterval = 30</source>
Interval in seconds to check the RSA cache and re-populate if less than rsacachecount.

<source lang="bash">com.openexchange.guard.rsacertainty = 256</source>
Bit certainty for RSA key generation. Higher numbers assure the number is in fact prime but time consuming. Lower is much faster. May need to be lower if not using cache.

=== Passwords ===

<source lang="bash">com.openexchange.guard.newpasslength=8</source>
Length of the randomly generated passwords when a user resets password.

<source lang="bash">com.openexchange.guard.minpasswordlength=6</source>
Minimum password length.

=== Backend ===

<source lang="bash">com.openexchange.guard.oxbackendpath = /ajax/</source>
URL used to communicated directly with the OX backend.

<source lang="bash">com.openexchange.guard.oxbackendidletime = 60</source>
HTTP connections to the backend are kept open for faster response. This is the timeout setting that will close idle connections.

=== Guest Accounts ===

<source lang="bash">com.openexchange.guard.shardsize=1000</source>
Guest users data are placed in databases oxguard_x. After set number of users, another database shard is created

<source lang="bash">com.openexchange.guard.guestCleanedAfterDaysOfInactivity=365</source>
Specifies how long emails and guest accounts are maintained for guests that have not had any
activity. If the guest has not logged into the Guest account in the configured time, the
emails are removed and the Guest account is closed.
0 implies indefinite (no cleaning done). Default 365 days

=== Recovery ===

If you do not want password recovery available, you can disable by adding

<source lang="bash">com.openexchange.guard.noRecovery = true</source>
Keep in mind, that a lost password will result in total loss of encrypted data.

=== Miscellaneous ===

<source lang="bash">com.openexchange.guard.secureReply = true</source>
(since Guard 2.2) Normally, when a person replies from an encrypted email, the reply is automatically encrypted. Set to false to disable this automatic encryption

== SSL ==

Starting with 2.4.0, OX Guard is running inside the OSGi container, meaning that all its servlets are being registered and served by Grizzly.

=== API SSL ===

<source lang="bash">com.openexchange.guard.backendSSL = false</source>
Per default the connection between the Guard backend and the configured Open-Xchange
REST API host is unencrypted. Even though that Guard will never transmit unencrypted
emails to or from the REST API you can optionally encrypt the whole communication between
those two components by using SSL. Please note: Enabling SSL might decrease performance
and/or create more system load due to additional encoding of the HTTP streams.

=== Incoming SSL ===

The communication between the frontend load balancer (Apache or otherwise) to Guard is by default HTTP (if protected network). More information on how to enable SSL you can find [http://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#X-FORWARDED-PROTO_Header here].

AppSuite:OX Guard Configuration 2 10

2019-03-21T16:49:45Z

Greg.hill: /* PGP */

= OX Guard 2.10 Configuration =

There are two main files for configuring OX Guard: <code>guard-api.properties</code> and <code>guard-core.properties</code>. The first configuration file is part of the OX backend and contains properties, among others, that enable the OX Guard functionality for various modules such as Mail and Drive as well as some capabilities. The second configuration file is part of the OX Guard and contains properties that configures the behaviour of the product.

== Configuration File (<code>guard-api.properties</code>) ==

=== Main Properties ===

<source lang="bash">com.openexchange.capability.guard = true</source>
Enables Guard. If not set, no guard functions will be loaded in the UI. Needed if users should be able to do ANY Guard functions including reading encrypted emails. This level will allow users without "guard-mail" enabled to read emails sent to them, reply to those emails, but not create new emails. Recommended minimum level for all users.

<source lang="bash">com.openexchange.capability.guard-mail = true</source>
Enables the user(s) ability to send encrypted emails. If False but guard enabled, they can read encrypted emails and reply to the original sender, but they cannot compose new emails

<source lang="bash">com.openexchange.capability.guard-drive = true</source>
Enables the drive functionality. If false, user(s) will not be able to decode nor upload new encrypted files

=== Optional Properties ===

<source lang="bash">com.openexchange.guard.templateID = 0</source>
Define template customization ID for the Guest reader emails, the Guest reader, and system emails. See [https://oxpedia.org/wiki/index.php?title%20=%20AppSuite:GuardCustomization Customization] for details.

<source lang="bash">com.openexchange.guard.endpoint =</source>
Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8009/guardadmin. By default is empty.

==== Capabilities ====

<source lang="bash">com.openexchange.capability.guard-nodeleterecovery = true</source>
(Guard 2.0) Disable the ability of the user to delete the recovery keys. Makes it impossible to reset password, but also adds level of protection/security

<source lang="bash">com.openexchange.capability.guard-nodeleteprivate = true</source>
(Guard 2.0) Disable the ability of the user to delete their private key. They can revoke it, but not delete the key.

<source lang="bash">com.openexchange.capability.guard-nodeleteonrevoke = true</source>
(Deprecated as of Guard 2.0) Default when revoking an item is to delete the content key, making the item impossible to decode. If this option is true, then the item is merely expired and can later be retrieved for decoding in case of legal requirements, corporate requirements, etc

<source lang="bash">com.openexchange.capability.guard-noextra = true</source>
(Deprecated as of Guard 2.0) Disables the ability to add an extra password to encrypted items. May be required by some industry

== Configuration File (<code>guard-core.properties</code>) ==

=== Database ===

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname = localhost</source>
The address of the MySQL database for OX Guard data. May be the same as the OX MySQL database.

<source lang="bash">com.openexchange.guard.oxguardDatabaseRead</source>
Optional read-only IP/name for the OX Guard database that might be used in Master-Slave setups.

<source lang="bash">com.openexchange.guard.oxguardShardDatabase</source>
IP/Name for the location of the Guest database shards. Additional shards will be created on this database

<source lang="bash">com.openexchange.guard.oxguardShardRead</source>
Optional read-only IP/name for Guest database shards that might be used in Master-Slave setups.

<source lang="bash">com.openexchange.guard.databaseUsername = username</source>
The username to access the OX Backend and Guard database. This user needs to have select, create, lock, insert, update privileges. Guard database user also should have alter (for updates), drop, index.

<source lang="bash">com.openexchange.guard.databasePassword = password</source>
The password for the databases

=== OX API ===

<source lang="bash">com.openexchange.guard.restApiHostname = localhost</source>
The address for the OX REST API. It would be the location of the OX Backend

<source lang="bash">com.openexchange.guard.OXBackendPort = 8009</source>
The port for the OX Backend. Default is 8009 (which is direct communication with the backend). Could be 80, etc, if going through load balancers

<source lang="bash">com.openexchange.guard.restApiUsername = open-xchange com.openexchange.guard.restApiPassword = secret</source>
Username and password for the REST API

<source lang="bash">com.openexchange.guard.externalEmailURL = example.com/appsuite/api/oxguard/reader/reader.html</source>
When Guard sends an encrypted eMail to members, they may not be using the webmail UI to read the email. A help file is attached, and a link will be provided to log into their webmail to read the encrypted item. This setting is used to point to a generic log in for the webmail system. Sent to multiple recipients, so not customized to the individual recipient.

=== Support API ===

<source lang="bash">com.openexchange.guard.supportapiusername = xxxxx
com.openexchange.guard.supportapipassword = yyyyy</source>
If the support API is to be used, a username and password should be configured.

<source lang="bash">com.openexchange.guard.exposedKeyDurationInHours = 168</source>
When a user is deleted, the Private keys are saved in a temporary deleted Keys table (in case of accidental deletion). If support "exposes" the key, the user can then retrieve it using link generated. For security reasons, this link is only valid for a short period of time. This property defines that duration.

=== File Storage ===

Local/remote storage is required for temporary caching of encrypted emails to guest/non-OX users. This can be an attached local file store, or Amazon S3 compatible object store depending on which <code>open-xchange-guard-*-storage</code> package is installed (<code>file</code> or <code>S3</code>).

==== General Properties ====

<source lang="bash">com.openexchange.guard.guestCleanedAfterDaysOfInactivity=365</source>
Specifies how long emails and guest accounts are maintained for guests that have not had any activity. If the guest has not logged into the Guest account in the configured time, the emails are removed and the Guest account is closed.

=== Storage Specific Properties ===

==== File-Storage ====

<source lang="bash">com.openexchange.guard.storage.file.uploadDirectory = /var/spool/open-xchange/guard/uploads</source>
Defines the temporary upload and cache directory for OX Guard Drive files for <code>open-xchange-guard-file-storage</code> package.
This directory needs to be shared between application servers serving the Guest Reader interface.

==== S3-Storage ====

<source lang="bash">com.openexchange.guard.storage.s3.endpoint =
com.openexchange.guard.storage.s3.bucketName =
com.openexchange.guard.storage.s3.region =
com.openexchange.guard.storage.s3.accessKey =
com.openexchange.guard.storage.s3.secretKey =</source>
S3 configuration options if the package <code>open-xchange-guard-s3-storage</code> is selected.

=== Crypto ===

<source lang="bash">com.openexchange.guard.aesKeyLength=256 (Depreciated)</source>
AES Key length. 256 is preferred, but not supported on all systems. May need to have the [http://www.oracle.com/technetwork/java/javase/downloads/index.html Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files] installed.

<source lang="bash">com.openexchange.guard.rsaKeyLength=2048</source>
RSA key length. Used when creating PGP keys

=== PGP ===

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
List of PGP Public key servers to query for public keys

<source lang="bash">com.openexchange.guard.publicKeyWhitelist</source>
A list of IP addresses of TRUSTED Guard servers. When the public PGP key server is queried, it will normally only find Guard keys that have already been created. If on the whitelist, the Guard server will also query the OX backend to see if the email address exists on the OX system, and if so, will create new keys for the user.

<source lang="bash">com.openexchange.guard.keyValidDays = 3650</source>
PGP keys created will only be valid for this number of days. Default is 10 years. Set to 0 if no expiration date.

<source lang="bash">com.openexchange.guard.pgpCacheDays=7</source>
When looking up remote PGP keys, if found, the keys will be stored in a temporary cache. Set number of days until the cache item is expired and remote lookup is repeated.

<pre>com.openexchange.guard.useStartTLS = true</pre>
Use TLS when delivering to the SMTP server when available

=== Email ===

<source lang="bash">com.openexchange.guard.guestSMTPServer=smtp.example.com
com.openexchange.guard.guestSMTPPort=25
com.openexchange.guard.guestSMTPUsername=
com.openexchange.guard.guestSMTPPassword=</source>
SMTP settings for outgoing emails from the guest reader. Emails sent from within the system use the OX Backend. The guest reader, however, sends replies through this SMTP. In addition, password emails (reset, initial) are sent through the SMTP server.

=== Bad Attempts ===

<source lang="bash">com.openexchange.guard.badMinuteLock = 10</source>
Defines how long someone will be locked out after bad attempts. Defaults to 10 minutes.

<source lang="bash">com.openexchange.guard.badPasswordCount = 5</source>
Defines how many times a person can attempt to unlock an encrypted item before being locked out. Defaults to 5 times.

=== RSA Key Generation ===

<source lang="bash">com.openexchange.guard.rsacache = true</source>
RSA keys are pre-generated in the background, encrypted, and stored for future user keys. RSA key generation is the most time consuming function and the RSA cache significantly improves new user creation time.

<source lang="bash">com.openexchange.guard.rsacachecount = 100</source>
Number of RSA keys to pre-generate

<source lang="bash">com.openexchange.guard.keycachecheckinterval = 30</source>
Interval in seconds to check the RSA cache and re-populate if less than rsacachecount.

<source lang="bash">com.openexchange.guard.rsacertainty = 256</source>
Bit certainty for RSA key generation. Higher numbers assure the number is in fact prime but time consuming. Lower is much faster. May need to be lower if not using cache.

=== Passwords ===

<source lang="bash">com.openexchange.guard.newpasslength=8</source>
Length of the randomly generated passwords when a user resets password.

<source lang="bash">com.openexchange.guard.minpasswordlength=6</source>
Minimum password length.

=== Backend ===

<source lang="bash">com.openexchange.guard.oxbackendpath = /ajax/</source>
URL used to communicated directly with the OX backend.

<source lang="bash">com.openexchange.guard.oxbackendidletime = 60</source>
HTTP connections to the backend are kept open for faster response. This is the timeout setting that will close idle connections.

=== Guest Accounts ===

<source lang="bash">com.openexchange.guard.shardsize=1000</source>
Guest users data are placed in databases oxguard_x. After set number of users, another database shard is created

=== Recovery ===

If you do not want password recovery available, you can disable by adding

<source lang="bash">com.openexchange.guard.noRecovery = true</source>
Keep in mind, that a lost password will result in total loss of encrypted data.

=== Miscellaneous ===

<source lang="bash">com.openexchange.guard.secureReply = true</source>
(since Guard 2.2) Normally, when a person replies from an encrypted email, the reply is automatically encrypted. Set to false to disable this automatic encryption

== SSL ==

Starting with 2.4.0, OX Guard is running inside the OSGi container, meaning that all its servlets are being registered and served by Grizzly.

=== API SSL ===

<source lang="bash">com.openexchange.guard.backendSSL = false</source>
Per default the connection between the Guard backend and the configured Open-Xchange
REST API host is unencrypted. Even though that Guard will never transmit unencrypted
emails to or from the REST API you can optionally encrypt the whole communication between
those two components by using SSL. Please note: Enabling SSL might decrease performance
and/or create more system load due to additional encoding of the HTTP streams.

=== Incoming SSL ===

The communication between the frontend load balancer (Apache or otherwise) to Guard is by default HTTP (if protected network). More information on how to enable SSL you can find [http://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#X-FORWARDED-PROTO_Header here].

AppSuite:OX Guard Upgrade 2 10

2019-03-14T12:30:31Z

Greg.hill: /* Guest Users */

= Upgrading OX Guard to 2.10 from 2.6/2.8 =

== Introduction ==

With '''OX Guard 2.10.0''' the experience for external recipients has changed significantly. Pre 2.10, there was a guest reader HTML package that allowed recipients to decrypt and reply to PGP emails. This has now changed. External recipients now have an Appsuite Guest account created, similar to a file share, with an pseudo inbox that lists all of the encrypted emails sent to them. The recipient will still be able to reply to emails sent to them, but will not be able to create new emails.

Bringing external users into Appsuite presents additional upsell opportunity as well as advertising options.

== Changes ==

This section covers the changes introduced with OX Guard 2.10.0.

=== Guest Users ===

All Guest users must have guard capability in order to read encrypted emails. To do this, the following configuration file <code>/opt/open-xchange/etc/share.properties</code> needs to be modified.

Assuming the guestCapabilityMode is set to static, please add guard to the staticGuestCapabilities

com.openexchange.share.guestCapabilityMode=static
com.openexchange.share.staticGuestCapabilities=guard

Also, make sure that the guest sessions are not treated as transient

com.openexchange.share.transientSessions=false

=== WebKey Service ===

Optional WebKey server was added in 2.10. This allows external users to look up the public PGP keys of Guard users as described [https://tools.ietf.org/html/draft-koch-openpgp-webkey-service-02 here]. To enable this ability, an additional ProxyPass needs to be added to the proxy_http.conf file

ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu

=== Reader Package ===

The package com.openexchange.guard.reader is no longer required, but recommended for those upgrading from an earlier version.
The package no longer contains a full guest reader, rather it redirects old Guard guest share links to the new appsuite guest. This package will be required for as long as old guest emails should remain functional.

=== Configuration Changes ===

==== Guest Configuration ====

Encrypted emails sent to external recipients was previously cached for a period of time, defaulting to 90 days. After this time, the reader would not function unless the user uploaded the attachment sent with their emails.

This has changed in 2.10. Now, a Guest user has a virtual inbox, listing the encrypted emails sent to them. A new configuration setting has been added

com.openexchange.guard.guestCleanedAfterDaysOfInactivity=365

This configuration cleans up a Guest account after the configured number of days if the user has not logged in. All emails for the guest account will be purged, and the Guest accounts removed from appsuite. A setting of 0 disables the cleaning completely.

==== Trust Levels ====

Some PGP Public keys can be trusted more than others. Guard now displays if the key is trusted or not by changing the color of the key next to a recipients email address, and provides details if the user hovers over the key. The trust level can be configured in the guard-core.properties file

com.openexchange.guard.keySources.trustThreshold=4
# The trust level for keys created by OX Guard
com.openexchange.guard.keySources.trustLevelGuard=5
# The trust level for keys uploaded by a user
com.openexchange.guard.keySources.trustLevelGuardUserUploaded=4
# The trust level for keys uploaded by a user and shared among users in the same context
com.openexchange.guard.keySources.trustLevelGuardUserShared=3
# The trust level for keys fetched from public HKP servers
com.openexchange.guard.keySources.trustLevelHKPPublicServer=1
# The trust level for keys fetched from HKP servers marked as trusted
com.openexchange.guard.keySources.trustLevelHKPTrustedServer=5
# The trust level for keys fetched from HKP servers queried via SRV DNS record
com.openexchange.guard.keySources.trustLevelHKPSRVServer=4
# The trust level for keys fetched from HKP servers queried via DNSSEC protected SRV DNS record
com.openexchange.guard.keySources.trustLevelHKPSRVDNSSECServer=4

==== Guest PIN ====

The option of adding an additional 4 digit pin to new Guest emails was completely re-written in 2.10. The prior config-cascade value of com.openexchange.capability.guard-pin is now used to specify at the user/context level if the PIN should be offered.

A new configuration '''com.openexchange.guard.pinEnabled''' was added to guard-core.properties file. This enabled the actual service. Please be sure to set to true if you want a PIN checked for new Guests.

Both of these need to be set to true for the PIN service to function properly

AppSuite:Multifactor

2019-02-06T15:19:24Z

Greg.hill: /* Login Page */

= Multifactor Authentication (since 7.10.2) =

Appsuite version 7.10.2 provides methods for users to require secondary, additional methods of authentication before creating a valid Appsuite session. These methods may include SMS messages, Time based authenticator methods, U2F compatible devices/keyfobs, and other custom methods.

== Enabling Multifactor ==

No additional packages are required for the core of multifactor authentication, although for some methods (such as SMS), additional packages will be required.

With SMS, for example, you must also install a provider, such as open-xchange-sms-sipgate.

Then, multifactor must be enabled as a capability. This can be done in the multifactor.properties file, or as a cascade value

com.openexchange.capability.multifactor=true

== Enabling SMS ==

First, the SMS provider must be installed and configured. Most will require a configured username and password, or AUTH_TOKEN. Install the needed package and configure.

At that point, you should enable SMS in the multifactor.properties file

com.openexchange.multifactor.sms.available=true

The following properties are also available

* com.openexchange.multifactor.sms.tokenLength (default is 8 characters)
* com.openexchange.multifactor.sms.tokenLifetime (Number of minutes until challenge expires)
* com.openexchange.multifactor.maxTokenAmount (Maximum number of challenges before locked out)

== Enabling TOTP ==

TOTP is Time-based One Time Password. This works with several apps available in mobile stores, such as Google Authenticator.

To enable, just set in the multifactor.properties file

com.openexchange.multifactor.totp.available=true

== Enabling Backup String ==

This is a method to allow a user to log into their account if they lose their primary multifactor authentication device (say losing their phone or U2F token). It is a long string that they can copy, download, or print to use to unlock the account in the event of loss

To enable, set in the multifactor.properties file

com.openexchange.multifactor.backupString.available=true

== Enabling U2F ==

U2F is supported in Google Chrome, as well as Firefox (though requires user changing advanced settings).

In multifactor.properties, enable U2F

com.openexchange.multifactor.U2F.available=true

Then, the domain that the user will be using must be specified. This will be used with the requests to the U2F device, and must mach the website. This configuration is config-cascade aware

com.openexchange.multifactor.U2F.appId=https://yourdomain

== Login Page ==

By default, the UI will change from the login page, draw the customized toolbar, then display a prompt for the multifactor authentication.

If you would prefer to have your login screen, or a different second factor screen used as the background, then you can configure in the as-config.yml

For example:

default:
host: all
signinTheme: default
multifactorBackground: pages/secondFactor

AppSuite:Multifactor

2019-02-05T20:08:03Z

Greg.hill:

= Multifactor Authentication (since 7.10.2) =

Appsuite version 7.10.2 provides methods for users to require secondary, additional methods of authentication before creating a valid Appsuite session. These methods may include SMS messages, Time based authenticator methods, U2F compatible devices/keyfobs, and other custom methods.

== Enabling Multifactor ==

No additional packages are required for the core of multifactor authentication, although for some methods (such as SMS), additional packages will be required.

With SMS, for example, you must also install a provider, such as open-xchange-sms-sipgate.

Then, multifactor must be enabled as a capability. This can be done in the multifactor.properties file, or as a cascade value

com.openexchange.capability.multifactor=true

== Enabling SMS ==

First, the SMS provider must be installed and configured. Most will require a configured username and password, or AUTH_TOKEN. Install the needed package and configure.

At that point, you should enable SMS in the multifactor.properties file

com.openexchange.multifactor.sms.available=true

The following properties are also available

* com.openexchange.multifactor.sms.tokenLength (default is 8 characters)
* com.openexchange.multifactor.sms.tokenLifetime (Number of minutes until challenge expires)
* com.openexchange.multifactor.maxTokenAmount (Maximum number of challenges before locked out)

== Enabling TOTP ==

TOTP is Time-based One Time Password. This works with several apps available in mobile stores, such as Google Authenticator.

To enable, just set in the multifactor.properties file

com.openexchange.multifactor.totp.available=true

== Enabling Backup String ==

This is a method to allow a user to log into their account if they lose their primary multifactor authentication device (say losing their phone or U2F token). It is a long string that they can copy, download, or print to use to unlock the account in the event of loss

To enable, set in the multifactor.properties file

com.openexchange.multifactor.backupString.available=true

== Enabling U2F ==

U2F is supported in Google Chrome, as well as Firefox (though requires user changing advanced settings).

In multifactor.properties, enable U2F

com.openexchange.multifactor.U2F.available=true

Then, the domain that the user will be using must be specified. This will be used with the requests to the U2F device, and must mach the website. This configuration is config-cascade aware

com.openexchange.multifactor.U2F.appId=https://yourdomain

== Login Page ==

By default, the UI will change from the login page, draw the customized toolbar, then display a prompt for the multifactor authentication.

If you would prefer to have your login screen, or a different second factor screen used as the background, then you can configure in the config.yml

For example:

default:
host: all
signinTheme: default
multifactorBackdround: pages/secondFactor

AppSuite:Multifactor

2019-02-05T20:06:45Z

Greg.hill: Created page with " = Multifactor Authentication (since 7.10.2) = Appsuite version 7.10.2 provides methods for users to require secondary, additional methods of authentication before creating a..."

= Multifactor Authentication (since 7.10.2) =

Appsuite version 7.10.2 provides methods for users to require secondary, additional methods of authentication before creating a valid Appsuite session. These methods may include SMS messages, Time based authenticator methods, U2F compatible devices/keyfobs, and other custom methods.

== Enabling Multifactor ==

No additional packages are required for the core of multifactor authentication, although for some methods (such as SMS), additional packages will be required.

With SMS, for example, you must also install a provider, such as open-xchange-sms-sipgate

Then, multifactor must be enabled as a capability. This can be done in the multifactor.properties file, or as a cascade value

com.openexchange.capability.multifactor=true

== Enabling SMS ==

First, the SMS provider must be installed and configured. Most will require a configured username and password, or AUTH_TOKEN. Install the needed package and configure

At that point, you should enable SMS in the multifactor.properties file

com.openexchange.multifactor.sms.available=true

The following properties are also available

* com.openexchange.multifactor.sms.tokenLength (default is 8 characters)
* com.openexchange.multifactor.sms.tokenLifetime (Number of minutes until challenge expires)
* com.openexchange.multifactor.maxTokenAmount (Maximum number of challenges before locked out)

== Enabling TOTP ==

TOTP is Time-based One Time Password. This works with several apps available in mobile stores, such as Google Authenticator.

To enable, just set in the multifactor.properties file

com.openexchange.multifactor.totp.available=true

== Enabling Backup String ==

This is a method to allow a user to log into their account if they lose their primary multifactor authentication device (say losing their phone or U2F token). It is a long string that they can copy, download, or print to use to unlock the account in the event of loss

To enable, set in the multifactor.properties file

com.openexchange.multifactor.backupString.available=true

== Enabling U2F ==

U2F is supported in Google Chrome, as well as Firefox (though requires user changing advanced settings).

In multifactor.properties, enable U2F

com.openexchange.multifactor.U2F.available=true

Then, the domain that the user will be using must be specified. This will be used with the requests to the U2F device, and must mach the website. This configuration is config-cascade aware

com.openexchange.multifactor.U2F.appId=https://yourdomain

== Login Page ==

By default, the UI will change from the login page, draw the customized toolbar, then display a prompt for the multifactor authentication.

If you would prefer to have your login screen, or a different second factor screen used as the background, then you can configure in the config.yml

For example:

default:
host: all
signinTheme: default
multifactorBackdround: pages/secondFactor

AppSuite:OX Guard

2018-10-05T14:27:10Z

Greg.hill: /* Redhat Enterprise Linux 7 or CentOS 7 */

= OX Guard (Version 2.4 - 2.8) =

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|-
|7.8.4
|2.8.0
|}

=== Important Notes ===

==== Customisation ====

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 Customisation] 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:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-guard-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code> and <code>open-xchange-guard-ui</code>.

The components required for the OX frontend are: <code>open-xchange-guard-ui-static</code> <code>open-xchange-guard-reader</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files).

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 7.0 (Wheezy) (valid until v2.4.2) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/2.4.2/guard/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/7.8.2/backend/DebianWheezy /</source>

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 open-xchange-guard-reader</source>

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage</source>

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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (Apache node).

=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>

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 open-xchange-guard-reader</source>

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== RedHat Enterprise Linux 6 or CentOS 6 ===

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/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

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 open-xchange-guard-reader</source>
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> 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</source>

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 open-xchange-guard-reader</source>
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>

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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 11 (valid until v2.4.2) ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/2.4.2/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/7.8.2/backend/SLES11 ox-backend</source>

and then run for a single node installation:

$ zypper ref
$ zypper in 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-reader</source>

or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>

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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) (valid until v2.4.2) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.4.2/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.8.2/backend/DebianWheezy /</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 8.0 (Jessie) ===

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/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</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 6 or CentOS 6 ===

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/RHEL6/
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/RHEL6/
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 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>

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== 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.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><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</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> 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 BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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 starting the initialization. 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</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.

'''Guard Mail''' and '''Guard Drive''' 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.

Each of those two 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 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>
==== Guard Drive: ====

<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 bakend.

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>

==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><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
</source>

Make sure that the balancer is properly configured in the <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>

==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== 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:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportApiUsername=
com.openexchange.guard.supportApiPassword=</source>
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 ===

<code>POST /guardsupport/?action=reset_password</code>

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:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (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 ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

=== Upgrade User (Release 2.10 and later) ===

<code>POST /guardsupport/?action=upgrade_guest</code>

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:

* <code>email</code> - The email address of the Guest user
* <code>user_id</code> – The user's new id
* <code>cid</code> - The user's new context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:Main Page Quickinstall

2018-07-03T16:38:34Z

Greg.hill: /* OX Guard */

= OX App Suite =

== Quick Installation Guide ==

To download and install the software, please use the following Installation Guides:

* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_8.0|Download and Installation Guide for Debian GNU/Linux 8.0 (Jessie)]]
* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_9.0|Download and Installation Guide for Debian GNU/Linux 9.0 (Stretch)]]
* [[AppSuite:Open-Xchange_Installation_Guide_for_SLES12|Download and Installation Guide for SUSE Linux Enterprise Server 12]]
* [[AppSuite:Open-Xchange_Installation_Guide_for_RHEL6|Download and Installation Guide for RedHat Enterprise Linux 6]]
* [[AppSuite:Open-Xchange_Installation_Guide_for_RHEL7|Download and Installation Guide for RedHat Enterprise Linux 7]]
* [[AppSuite:Open-Xchange_Installation_Guide_for_CentOS_6|Download and Installation Guide for CentOS 6]]
* [[AppSuite:Open-Xchange_Installation_Guide_for_CentOS_7|Download and Installation Guide for CentOS 7]]
* [[OXSE4UCS_Installation_en|Download and Installation Guide for Univention Corporate Server]]
* [[AppSuite:Demoinstallation|Download and Installation Guide for Open-Xchange SE / App Suite for UCS VMware© Demo]]

== Installing the latest Updates for OX App Suite ==

To get the latest features and bugfixes for OX App Suite, you need to have a valid license. The following article explains how that can be done:

* [[AppSuite:UpdatingOXPackages|Updating OX App Suite packages]]
* [[UpdateTasks|Update Task Management in Open-Xchange]]

== OX App Suite deployment tutorials ==

A complete guide of necessary tasks with a hardware and setup recommendation for different Open-Xchange Hosting environments:

* [[AppSuite:OX_Tutorial_10K|OX App Suite deployment tutorial for up to 10.000 Users]]
* [[AppSuite:OX_Tutorial_100K|OX App Suite deployment tutorial for up to 100.000 Users]]
* [[AppSuite:OX_Tutorial_1M|OX App Suite deployment tutorial for up to 1.000.000 Users]]

== Reporting Tool (Mandatory for Maintenance) ==

To receive maintenance in the future, the installation of the Open-Xchange Reporting Tool is mandatory. It documents the current state of your system installation. Furthermore, the tool runs a validity check for your current maintenance. Based on the reported detail information Open-Xchange will then be able to improve its own support and maintenance offerings for you. This article explains how that can be done:

* [https://documentation.open-xchange.com/7.10.0/middleware/components/report_client.html OX App Suite Reporting Client]

= Open-Xchange Additional Software =

== OX Documents ==

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

* [[AppSuite:Documents_Installation_Guide|OX Documents Download & Installation]]

== OX Guard ==

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.

* [[AppSuite:OX_Guard_2_10|Installation and information of OX Guard]]
* [[Appsuite:OX_Guard_Configuration_2_10|Configuration Options for OX Guard]]

== OX Drive ==

The OX Drive client lets you store and share your photos, files, documents and videos, anytime, anywhere. Access any file you save to OX Drive from all your computers, iPhone, iPad or from within OX App Suite itself.

* [[AppSuite:OX_Drive|Installation and information of OX Drive]]

== OX Mail App v2 ==

The OX Mail v2 is a companion app for OX App Suite, and brings the power of OX App Suite web-based email to your customers' mobile devices. The OX Mail v2 is a native app designed specifically for Android and iOS smartphones and tablets.

* [[AppSuite:OX_Mail_v2_0|Installation and information of OX Mail App v2]]

== OX Sync ==

=== Connector for Business Mobility (ActiveSync) ===

Connector for Business Mobility enables you to securely manage emails, contacts, calendar and tasks on a mobile device. It is based on Microsoft Exchange Active Sync (EAS) standard (valid Open-Xchange license required).

* [[AppSuite:Connector_for_Business_Mobility_Installation_Guide|Installation and information of the Connector for Business Mobility]]

=== Open-Xchange Contact Synchronization with CardDAV ===

The Mac OS X and iOS integration makes Open-Xchange contacts available to end users through their native applications.

* [[AppSuite:CardDAVClients | Configuration CardDAV with Open-Xchange]]
* [[AppSuite:Caldav_carddav_Bundles| Installation CardDAV with Open-Xchange]]

=== Open-Xchange Calendar synchronization with CalDAV ===

The Mac OS X, iOS and Thunderbird Lightning integration makes Open-Xchange appointments available to end users through their native applications.

* [[AppSuite:CalDAVClients | Configuration CalDAV with Open-Xchange]]
* [[AppSuite:Caldav_carddav_Bundles| Installation CalDAV with Open-Xchange]]

=== OX Sync App ===

OX Sync App is a native mobile phone app built specifically for smartphone users of Android, that also have a valid OX App Suite account. The app is designed to let users sync their OX App Suite Appointments, Tasks and Contacts environment directly from a native mobile phone client.

* [[AppSuite:OX_Sync_App|Installation and information of the OX Sync App]]

== eM Client for OX App Suite ==

Open-Xchange’s eM Client for OX App Suite is a full-featured email client with a modern and easy-to-use interface for Windows users. In addition to user-friendly email functionality, this application offers several integrated features: a calendar, tasks and contacts. Additionally, eM Client for OX App Suite can be used offline with full OX App Suite synchronization.

* [[AppSuite:EM_Client_for_OX_App_Suite|Download & Installation of eM Client for OX App Suite]]

== OX APS package for Odins Service Automation System and Plesk Panel ==

Odins Service Automation (OSA) is an operations support system (OSS) for service providers, who want to differentiate their offerings in order to reduce customer churn and attract new customers. Additional, the APS package adds a high performance, best in class email service to Odins Plesk Panel customers.

* [[Parallels_Integration|Integrate Open-Xchange with Odin]]

== OX APS 2.0 package for Odin Service Automation ==

Service Automation provides a single, centralized management console for managing offer and delivery of cloud services, and supports multiple tiers of service resellers with customizable white-labeled customer facing websites to initiate ordering and provisioning.

Service Automation provides access to all of the resources inside a service provider’s data center associated with cloud service offerings. The APS package adds a high performance, best in class email service to Odin's customers.

Attention: This APS 2.0 package is only for the Open-Xchange own OX as a Service platform or similar respective compatible deployments or copies of this platform.

* [[PA_APSv2_IntegrationGuide|OX APS 2.0 package for Odin Service Automation]]

== Dovecot Anti-Abuse Shield ==

Dovecot Anti-Abuse Shield is included along with Dovecot Pro, but works with both Dovecot Pro and OX App Suite as a component to protect against login/authentication abuse. Anti-Abuse Shield runs on a cluster of servers, and integrates with both OX App Suite and Dovecot to detect abuse, brute force attacks and also to enforce common authentication/authorization policies across the platform.

* [[AppSuite:Dovecot_Antiabuse_Shield|Dovecot Anti-Abuse Shield]]

= Open-Xchange Additional Tools and Configurations =

== Automated Deployment with Chef ==

For an automated deployment of our software have a look at our

* [[AppSuite:Deployment_with_Chef_Showcase|Community Showcase Deployment with Chef]]
* [[AppSuite:Deployment_with_Chef_for_Raspbian|Installation the Open-Xchange App Suite to a Raspberry Pi]]

== Open-Xchange Document Viewer ==
The OX Document Viewer will choose the best preview format depending on the users device on the OX App Suite Web Interface (valid Open-Xchange license required).

* [[AppSuite:DocumentViewer |Download & Install Document Viewer]]

== Open-Xchange Presenter ==

OX Presenter allows for local and remote presentations of presentation documents (valid Open-Xchange license required).

* [[AppSuite:Presenter_Installation_Guide|Download & Installation of OX Presenter]]

== Open-Xchange Updater ==

The Open-Xchange Updater is a software tool by Open-Xchange that installs the latest version of Open-Xchange client software on computers running Windows (valid Open-Xchange license required).

* [[AppSuite:Open-Xchange_Updater|Installation of the Open-Xchange Updater]]

== Cluster-Setup ==
Multiple Open-Xchange servers can form a cluster with inter-OX-communication over a network.

* [[AppSuite:Running_a_cluster| Configuration Cluster-Setup]]

== HTTP based Connector via Grizzly ==
OX App Suite offers a second HTTP based connector for the communication between the HTTP server and the backend. This new connector is based on Oracle's Project Grizzly - a NIO and Web framework.

* [[AppSuite:Grizzly| Configuration Connector based on Grizzly]]

== LDAP Contact Storage ==
Open-Xchange provides a new LDAP Contact Storage Integration Bundle. The new solution is available together with the current LDAP bundle.

* [[ContactStorageLDAP| LDAP Contact Storage]]

= Installation Information =

== Information ==

* [[AppSuite:Backend_API_changes_extensions|OX App Suite - API Changes & Extensions]]

== Installation Requirements ==

* The [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] provides an overview about the supported components at the OX User Front-End, Connector for Microsoft Outlook, Connector for Business Mobility and OX Notifier. This overview makes no claim to be complete.
* [[AppSuite:Importing_OX_Buildkey|Importing the Open-Xchange public buildkey]]

[[Category: OX7]]
[[Category: AppSuite]]

AppSuite:OX Guard

2018-06-14T11:20:39Z

Greg.hill: /* OX Guard (Version 2.4 - 2.8) */

= OX Guard (Version 2.4 - 2.8) =

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|-
|7.8.4
|2.8.0
|}

=== Important Notes ===

==== Customisation ====

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 Customisation] 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:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-guard-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code> and <code>open-xchange-guard-ui</code>.

The components required for the OX frontend are: <code>open-xchange-guard-ui-static</code> <code>open-xchange-guard-reader</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files).

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 7.0 (Wheezy) (valid until v2.4.2) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/2.4.2/guard/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/7.8.2/backend/DebianWheezy /</source>

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 open-xchange-guard-reader</source>

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage</source>

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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (Apache node).

=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>

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 open-xchange-guard-reader</source>

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== RedHat Enterprise Linux 6 or CentOS 6 ===

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/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

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 open-xchange-guard-reader</source>
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> 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</source>

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</source>
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>

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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 11 (valid until v2.4.2) ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/2.4.2/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/7.8.2/backend/SLES11 ox-backend</source>

and then run for a single node installation:

$ zypper ref
$ zypper in 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-reader</source>

or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>

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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) (valid until v2.4.2) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.4.2/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.8.2/backend/DebianWheezy /</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 8.0 (Jessie) ===

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/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</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 6 or CentOS 6 ===

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/RHEL6/
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/RHEL6/
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 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>

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== 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.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><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</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> 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 BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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 starting the initialization. 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</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.

'''Guard Mail''' and '''Guard Drive''' 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.

Each of those two 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 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>
==== Guard Drive: ====

<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 bakend.

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>

==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><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
</source>

Make sure that the balancer is properly configured in the <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>

==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== 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:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportApiUsername=
com.openexchange.guard.supportApiPassword=</source>
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 ===

<code>POST /guardsupport/?action=reset_password</code>

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:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (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 ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

=== Upgrade User (Release 2.10 and later) ===

<code>POST /guardsupport/?action=upgrade_guest</code>

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:

* <code>email</code> - The email address of the Guest user
* <code>user_id</code> – The user's new id
* <code>cid</code> - The user's new context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard

2018-06-14T11:19:49Z

Greg.hill: Undo revision 24036 by Khgras (talk)

= OX Guard (Version 2.4+) =

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|-
|7.8.4
|2.8.0
|}

=== Important Notes ===

==== Customisation ====

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 Customisation] 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:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-guard-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code> and <code>open-xchange-guard-ui</code>.

The components required for the OX frontend are: <code>open-xchange-guard-ui-static</code> <code>open-xchange-guard-reader</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files).

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 7.0 (Wheezy) (valid until v2.4.2) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/2.4.2/guard/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/7.8.2/backend/DebianWheezy /</source>

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 open-xchange-guard-reader</source>

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage</source>

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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (Apache node).

=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>

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 open-xchange-guard-reader</source>

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== RedHat Enterprise Linux 6 or CentOS 6 ===

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/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

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 open-xchange-guard-reader</source>
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> 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</source>

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</source>
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>

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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 11 (valid until v2.4.2) ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/2.4.2/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/7.8.2/backend/SLES11 ox-backend</source>

and then run for a single node installation:

$ zypper ref
$ zypper in 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-reader</source>

or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>

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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) (valid until v2.4.2) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.4.2/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.8.2/backend/DebianWheezy /</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 8.0 (Jessie) ===

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/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</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 6 or CentOS 6 ===

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/RHEL6/
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/RHEL6/
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 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>

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== 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.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><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</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> 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 BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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 starting the initialization. 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</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.

'''Guard Mail''' and '''Guard Drive''' 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.

Each of those two 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 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>
==== Guard Drive: ====

<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 bakend.

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>

==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><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
</source>

Make sure that the balancer is properly configured in the <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>

==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== 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:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportApiUsername=
com.openexchange.guard.supportApiPassword=</source>
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 ===

<code>POST /guardsupport/?action=reset_password</code>

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:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (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 ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

=== Upgrade User (Release 2.10 and later) ===

<code>POST /guardsupport/?action=upgrade_guest</code>

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:

* <code>email</code> - The email address of the Guest user
* <code>user_id</code> – The user's new id
* <code>cid</code> - The user's new context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard Upgrade 2 10

2018-06-08T14:34:38Z

Greg.hill: /* Guest PIN */

= Upgrading OX Guard to 2.10 from 2.6/2.8 =

== Introduction ==

With '''OX Guard 2.10.0''' the experience for external recipients has changed significantly. Pre 2.10, there was a guest reader HTML package that allowed recipients to decrypt and reply to PGP emails. This has now changed. External recipients now have an Appsuite Guest account created, similar to a file share, with an pseudo inbox that lists all of the encrypted emails sent to them. The recipient will still be able to reply to emails sent to them, but will not be able to create new emails.

Bringing external users into Appsuite presents additional upsell opportunity as well as advertising options.

== Changes ==

This section covers the changes introduced with OX Guard 2.10.0.

=== Guest Users ===

All Guest users must have guard capability in order to read encrypted emails. To do this, the following configuration file <code>/opt/open-xchange/etc/share.properties</code> needs to be modified.

Assuming the guestCapabilityMode is set to static, please add guard to the staticGuestCapabilities

com.openexchange.share.guestCapabilityMode=static
com.openexchange.share.staticGuestCapabilities=guard

=== WebKey Service ===

Optional WebKey server was added in 2.10. This allows external users to look up the public PGP keys of Guard users as described [https://tools.ietf.org/html/draft-koch-openpgp-webkey-service-02 here]. To enable this ability, an additional ProxyPass needs to be added to the proxy_http.conf file

ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu

=== Reader Package ===

The package com.openexchange.guard.reader is no longer required, but recommended for those upgrading from an earlier version.
The package no longer contains a full guest reader, rather it redirects old Guard guest share links to the new appsuite guest. This package will be required for as long as old guest emails should remain functional.

=== Configuration Changes ===

==== Guest Configuration ====

Encrypted emails sent to external recipients was previously cached for a period of time, defaulting to 90 days. After this time, the reader would not function unless the user uploaded the attachment sent with their emails.

This has changed in 2.10. Now, a Guest user has a virtual inbox, listing the encrypted emails sent to them. A new configuration setting has been added

com.openexchange.guard.guestCleanedAfterDaysOfInactivity=365

This configuration cleans up a Guest account after the configured number of days if the user has not logged in. All emails for the guest account will be purged, and the Guest accounts removed from appsuite. A setting of 0 disables the cleaning completely.

==== Trust Levels ====

Some PGP Public keys can be trusted more than others. Guard now displays if the key is trusted or not by changing the color of the key next to a recipients email address, and provides details if the user hovers over the key. The trust level can be configured in the guard-core.properties file

com.openexchange.guard.keySources.trustThreshold=4
# The trust level for keys created by OX Guard
com.openexchange.guard.keySources.trustLevelGuard=5
# The trust level for keys uploaded by a user
com.openexchange.guard.keySources.trustLevelGuardUserUploaded=4
# The trust level for keys uploaded by a user and shared among users in the same context
com.openexchange.guard.keySources.trustLevelGuardUserShared=3
# The trust level for keys fetched from public HKP servers
com.openexchange.guard.keySources.trustLevelHKPPublicServer=1
# The trust level for keys fetched from HKP servers marked as trusted
com.openexchange.guard.keySources.trustLevelHKPTrustedServer=5
# The trust level for keys fetched from HKP servers queried via SRV DNS record
com.openexchange.guard.keySources.trustLevelHKPSRVServer=4
# The trust level for keys fetched from HKP servers queried via DNSSEC protected SRV DNS record
com.openexchange.guard.keySources.trustLevelHKPSRVDNSSECServer=4

==== Guest PIN ====

The option of adding an additional 4 digit pin to new Guest emails was completely re-written in 2.10. The prior config-cascade value of com.openexchange.capability.guard-pin is now used to specify at the user/context level if the PIN should be offered.

A new configuration '''com.openexchange.guard.pinEnabled''' was added to guard-core.properties file. This enabled the actual service. Please be sure to set to true if you want a PIN checked for new Guests.

Both of these need to be set to true for the PIN service to function properly

AppSuite:OX Guard Upgrade 2 10

2018-06-08T14:24:26Z

Greg.hill: /* Configuration Changes */

= Upgrading OX Guard to 2.10 from 2.6/2.8 =

== Introduction ==

With '''OX Guard 2.10.0''' the experience for external recipients has changed significantly. Pre 2.10, there was a guest reader HTML package that allowed recipients to decrypt and reply to PGP emails. This has now changed. External recipients now have an Appsuite Guest account created, similar to a file share, with an pseudo inbox that lists all of the encrypted emails sent to them. The recipient will still be able to reply to emails sent to them, but will not be able to create new emails.

Bringing external users into Appsuite presents additional upsell opportunity as well as advertising options.

== Changes ==

This section covers the changes introduced with OX Guard 2.10.0.

=== Guest Users ===

All Guest users must have guard capability in order to read encrypted emails. To do this, the following configuration file <code>/opt/open-xchange/etc/share.properties</code> needs to be modified.

Assuming the guestCapabilityMode is set to static, please add guard to the staticGuestCapabilities

com.openexchange.share.guestCapabilityMode=static
com.openexchange.share.staticGuestCapabilities=guard

=== WebKey Service ===

Optional WebKey server was added in 2.10. This allows external users to look up the public PGP keys of Guard users as described [https://tools.ietf.org/html/draft-koch-openpgp-webkey-service-02 here]. To enable this ability, an additional ProxyPass needs to be added to the proxy_http.conf file

ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu

=== Reader Package ===

The package com.openexchange.guard.reader is no longer required, but recommended for those upgrading from an earlier version.
The package no longer contains a full guest reader, rather it redirects old Guard guest share links to the new appsuite guest. This package will be required for as long as old guest emails should remain functional.

=== Configuration Changes ===

==== Guest Configuration ====

Encrypted emails sent to external recipients was previously cached for a period of time, defaulting to 90 days. After this time, the reader would not function unless the user uploaded the attachment sent with their emails.

This has changed in 2.10. Now, a Guest user has a virtual inbox, listing the encrypted emails sent to them. A new configuration setting has been added

com.openexchange.guard.guestCleanedAfterDaysOfInactivity=365

This configuration cleans up a Guest account after the configured number of days if the user has not logged in. All emails for the guest account will be purged, and the Guest accounts removed from appsuite. A setting of 0 disables the cleaning completely.

==== Trust Levels ====

Some PGP Public keys can be trusted more than others. Guard now displays if the key is trusted or not by changing the color of the key next to a recipients email address, and provides details if the user hovers over the key. The trust level can be configured in the guard-core.properties file

com.openexchange.guard.keySources.trustThreshold=4
# The trust level for keys created by OX Guard
com.openexchange.guard.keySources.trustLevelGuard=5
# The trust level for keys uploaded by a user
com.openexchange.guard.keySources.trustLevelGuardUserUploaded=4
# The trust level for keys uploaded by a user and shared among users in the same context
com.openexchange.guard.keySources.trustLevelGuardUserShared=3
# The trust level for keys fetched from public HKP servers
com.openexchange.guard.keySources.trustLevelHKPPublicServer=1
# The trust level for keys fetched from HKP servers marked as trusted
com.openexchange.guard.keySources.trustLevelHKPTrustedServer=5
# The trust level for keys fetched from HKP servers queried via SRV DNS record
com.openexchange.guard.keySources.trustLevelHKPSRVServer=4
# The trust level for keys fetched from HKP servers queried via DNSSEC protected SRV DNS record
com.openexchange.guard.keySources.trustLevelHKPSRVDNSSECServer=4

==== Guest PIN ====

The option of adding an additional 4 digit pin to new Guest emails was completely re-written in 2.10. The prior config-cascade value of com.openexchange.capability.guard-pin has been depreciated.
A new configuration '''com.openexchange.guard.pinEnabled''' was added to guard-core.properties file. Please use this configuration instead

AppSuite:OX System Requirements

2018-03-19T13:29:39Z

Greg.hill: /* OX Guard */

= OX App Suite Requirements - Open-Xchange supported components overview =

The following table provides an overview about the supported components at the OX User Front-End, Connector for Microsoft Outlook and Connector for Business Mobility. This overview makes no claim to be complete.

Open-Xchange Server 6 overview tables about the supported components at the OX User Front-End, Connector for Microsoft Outlook and Connector for Business Mobility are available at [[OX_System_Requirements|OX 6 Requirements - Open-Xchange supported components overview]]

Information about Maintenance expiries of components, versions and browser support, can be found in the [[AppSuite:Versioning_and_Numbering#Maintenance_expires|Maintenance Expires Table]]

== Installation-, Hardware-, Software-Requirements ==

Please note: Installation and administration of the OX App Suite requires basic knowledge of E-Mail systems under Linux, Apache and MySQL as well as experience in the command line administration of Linux systems.

'''OX App Suite:'''
* Memory 8 GB - 12 GB <br> '''Please Note: If you want to install OX in a VM memory needs to be allocated exclusively to that installation (and not shared with other VM's). This also applies to the database and other related systems or components.'''
* Disk 500 MB plus User Data
* Supported Platform Architecture: 64 bit Operation Systems (x84_64)
* Supported IMAP Server: Dovecot (Recommended), Cyrus and Courier (To some extent, may mot support all features)

== Desktop Browser (Minimum display resolution: 1024 x 768)==

{|border="2" rules="all" align="left">
|'''Browser'''
|'''OX App Suite User Front-End'''
|-
| 
| 
|-
|Microsoft Internet Explorer 10/11
|v7.6.3
|-
|Microsoft Internet Explorer 11/Edge
|v7.8.3, v7.8.4
|-
|Mozilla Firefox (latest & previous version)
|v7.8.3, v7.8.4
|-
|Google Chrome (latest & previous version)
|v7.8.3, v7.8.4
|-
|Apple Safari (10.01 & 10.03; Mac OS X only)
|v7.8.3, v7.8.4
|-
|}

== Mobile Device Support==

{|border="2" rules="all" align="left">
|'''Mobile Device'''
|'''Supported Browser'''
|'''OX App Suite User Front-End'''
|'''Minimum Speed Requirements'''
|-
| 
| 
| 
| 
|-
|iPhone on iOS 9 / iOS 10 / iOS 11
|Safari
|v7.8.3, v7.8.4
|3G connections (512/256kBit/s, 350ms latency)
|-
|Smartphone on Android 4.1 or later
|Chrome (latest & previous version)
|v7.8.3, v7.8.4
|3G connections (512/256kBit/s, 350ms latency)
|}

== Tablet Support==

{|border="2" rules="all" align="left">
|'''Tablet'''
|'''Supported Browser'''
|'''OX App Suite User Front-End'''
|'''Minimum Speed Requirements'''
|-
| 
| 
| 
| 
|-
|Apple iPad (all devices) on iOS 9 / iOS 10 / iOS 11
|Safari
|v7.8.3, v7.8.4
|3G connections (512/256kBit/s, 350ms latency)
|-
|Tablets on Android 4.1 or later
|Chrome (latest & previous version)
|v7.8.3, v7.8.4
|3G connections (512/256kBit/s, 350ms latency)
|}

== MS Windows / MS Outlook® / OX Updater ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|[http://oxpedia.org/wiki/index.php?title=AppSuite:Connector_for_Microsoft_Outlook '''Connector for Microsoft Outlook''']
|'''OX Updater'''
|-
| 
| 
| 
|-
|OX App Suite
|[[File:check.gif]]
|[[File:check.gif]]
|-
|Client PC operating system
|Latest versions of Windows 8 (no support of start screen tiles), latest versions of Windows 10 (no support of Mac OS X clients with emulators and Windows RT)
|Latest versions of Windows 8 (no support of start screen tiles), latest versions of Windows 10 (no support of Mac OS X clients with emulators and Windows RT)
|-
|Supported Outlook versions
|Latest versions of Microsoft Outlook 2010 (each with 32 + 64 bit), Outlook 2013 and Outlook 2016 (each with 32 + 64 bit; no support of "Office 2010 Click-to-Run", "Office Home and Business 2010 Testversion”)
| 
|-
|}

== Calendar/Contact synchronization Apple Mac OS X ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|Calendar synchronization with CalDAV
|Contacts synchronization with CardDAV
|-
| 
| 
| 
|-
|Mac OS X 10.11 (El Capitan)
|[[File:check.gif]]
|[[File:check.gif]]
|-
|macOS 10.12, 10.13 (Sierra & High Sierra)
|[[File:check.gif]]
|[[File:check.gif]]
|-
|}

== Calendar/Contact synchronization Apple iOS ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|Calendar synchronization with CalDAV
|Contacts synchronization with CardDAV
|-
| 
| 
| 
|-
|Apple iOS 9 / iOS 10 / iOS 11
|[[File:check.gif]]
|[[File:check.gif]]
|-
|}

== Mobility Solution - Supported- Platforms, Features and Devices ==

{|border="2" rules="all" align="left">
|'''Feature/Technology/Device'''
|[http://oxpedia.org/wiki/index.php?title=OXtender_for_Business_Mobility '''OXtender for Business Mobility'''] (availalble for App Suite, OXHE, OXSE)
|-
| 
| 
|-
|Exchange Active Sync 2.5
|[[File:check.gif]]
|-
|Exchange Active Sync 12.1
|[[File:check.gif]]
|-
| 
| 
|-
|Access and creation of emails
|[[File:check.gif]]
|-
|Personal PIM folder
|[[File:check.gif]]
|-
|Public and Shared PIM folder
|[[File:cross.gif]]
|-
|Global address book
|[[File:check.gif]]
|-
|Push E-Mail
|[[File:check.gif]]
|-
| 
| 
|-
|Windows Phone 8 (latest & previous minor versions), Windows Phone 10 (latest & previous minor versions)
|[[File:check.gif]]
|-
|Apple iOS 9 / iOS 10 / iOS 11
|[[File:check.gif]]
|-
|Android 4.1 or later
|[[File:check.gif]]
|-
|}

== OX Drive for Clients ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform'''
|-
| 
| 
|-
|OX App Suite
|OX App Suite v7.8.3, OX App Suite v7.8.4
|-
|OX Drive for Windows
|Latest versions of Windows 8, latest versions of Windows 10 (no support of Mac OS X clients with emulators and Windows RT)
|-
|OX Drive for Mac OS
|Mac OS X 10.11 (El Capitan), macOS 10.12, 10.13 (Sierra & High Sierra)
|-
|OX Drive for iOS
|Apple iOS 9, Apple iOS 10, Apple iOS 11
|-
|OX Drive for Android
|Smartphone on Android 4.1 or later with Chrome (latest & previous version), Tablets on Android 4.1 or later with Chrome (latest & previous version)
|-
|}

== OX Mail for Clients ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|OX App Suite
|OX App Suite v7.8.3, OX App Suite v7.8.4
|-
|OX Mail for iOS
|Apple iOS 9, Apple iOS 10
|-
|OX Mail for Android
|Smartphone on Android 4.3 or later
|-
|}

== OX Sync App ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|OX App Suite
|OX App Suite v7.8.3, OX App Suite v7.8.4
|-
|OX Sync App for Android
|Smartphone on Android 4.0 or later
|-
|}

== OX Guard ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|OX App Suite
|OX Guard since v2.6.0: OX App Suite v7.8.3<br>OX Guard since v2.8.0: OX App Suite v7.8.4<br>OX Guard since v2.10.0: OX App Suite v7.10.0
|-
|Mobile Device and Tablet Support
|Apple iPhone on iOS 9 / iOS 10 / iOS 11: Safari (latest version & previous version)<br>Smartphone on Android 4.1 or later: Chrome (latest & previous version)<br>Apple iPad (all devices) on iOS 9 / iOS 10 / iOS 11: Safari Safari (latest version & previous version)<br>Tablets on Android 4.1 or later: Chrome (latest & previous version)
|-
|}

== eM Client for OX App Suite ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|[http://oxpedia.org/wiki/index.php?title=AppSuite:EM_Client_for_OX_App_Suite '''eM Client for OX App Suite''']
|-
| 
| 
|-
|OX App Suite
|OX App Suite v7.8.3, OX App Suite v7.8.4
|-
|Client PC operating system
|Latest versions of Windows 8 (no support of start screen tiles), latest versions of Windows 10 (no support of Mac OS X clients with emulators and Windows RT)
|-
|}

== Server Platforms ==

{|border="2" rules="all" align="left">
|'''Platforms'''
|'''Supported Java Versions'''
|'''Supported Database'''
|-
| 
| 
| 
|-
|Suse Linux Enterprise Server 12
|OpenJDK 7
|MariaDB 10.0
|-
|Red Hat Enterprise Linux 6
|OpenJDK 7
|MySQL 5.1
|-
|Red Hat Enterprise Linux 7
|OpenJDK 8
|MariaDB 5.5
|-
|Debian 8 (Jessie)
|OpenJDK 7
|MySQL 5.5, MariaDB 10.1
|-
|CentOS 6
|OpenJDK 7
|MySQL 5.1
|-
|CentOS 7
|OpenJDK 8
|MariaDB 5.5
|-
|Univention Corporate Server 4
|OpenJDK 7
|MySQL 5.5
|-
|}

'''Please Note: To gain higher availability a setup based on Percona XtraDB Cluster is supported like described in this article: [http://oxpedia.org/wiki/index.php?title=OXLoadBalancingClustering_Database Galera database setup]. Open-Xchange supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database and starting with OX 7.8.0 also version 5.6.x.

[[Category: OX7]]
[[Category: AppSuite]]

AppSuite:OX Guard Configuration 2 10

2018-03-13T13:47:33Z

Greg.hill: /* Initial 2.10 configuration */

= OX Guard 2.10 Configuration =

There are two main files for configuring OX Guard: <code>guard-api.properties</code> and <code>guard-core.properties</code>. The first configuration file is part of the OX backend and contains properties, among others, that enable the OX Guard functionality for various modules such as Mail and Drive as well as some capabilities. The second configuration file is part of the OX Guard and contains properties that configures the behaviour of the product.

== Configuration File (<code>guard-api.properties</code>) ==

=== Main Properties ===

<source lang="bash">com.openexchange.capability.guard = true</source>
Enables Guard. If not set, no guard functions will be loaded in the UI. Needed if users should be able to do ANY Guard functions including reading encrypted emails. This level will allow users without "guard-mail" enabled to read emails sent to them, reply to those emails, but not create new emails. Recommended minimum level for all users.

<source lang="bash">com.openexchange.capability.guard-mail = true</source>
Enables the user(s) ability to send encrypted emails. If False but guard enabled, they can read encrypted emails and reply to the original sender, but they cannot compose new emails

<source lang="bash">com.openexchange.capability.guard-drive = true</source>
Enables the drive functionality. If false, user(s) will not be able to decode nor upload new encrypted files

=== Optional Properties ===

<source lang="bash">com.openexchange.guard.templateID = 0</source>
Define template customization ID for the Guest reader emails, the Guest reader, and system emails. See [https://oxpedia.org/wiki/index.php?title%20=%20AppSuite:GuardCustomization Customization] for details.

<source lang="bash">com.openexchange.guard.endpoint =</source>
Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8009/guardadmin. By default is empty.

==== Capabilities ====

<source lang="bash">com.openexchange.capability.guard-nodeleterecovery = true</source>
(Guard 2.0) Disable the ability of the user to delete the recovery keys. Makes it impossible to reset password, but also adds level of protection/security

<source lang="bash">com.openexchange.capability.guard-nodeleteprivate = true</source>
(Guard 2.0) Disable the ability of the user to delete their private key. They can revoke it, but not delete the key.

<source lang="bash">com.openexchange.capability.guard-nodeleteonrevoke = true</source>
(Deprecated as of Guard 2.0) Default when revoking an item is to delete the content key, making the item impossible to decode. If this option is true, then the item is merely expired and can later be retrieved for decoding in case of legal requirements, corporate requirements, etc

<source lang="bash">com.openexchange.capability.guard-noextra = true</source>
(Deprecated as of Guard 2.0) Disables the ability to add an extra password to encrypted items. May be required by some industry

== Configuration File (<code>guard-core.properties</code>) ==

=== Database ===

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname = localhost</source>
The address of the MySQL database for OX Guard data. May be the same as the OX MySQL database.

<source lang="bash">com.openexchange.guard.oxguardDatabaseRead</source>
Optional read-only IP/name for the OX Guard database that might be used in Master-Slave setups.

<source lang="bash">com.openexchange.guard.oxguardShardDatabase</source>
IP/Name for the location of the Guest database shards. Additional shards will be created on this database

<source lang="bash">com.openexchange.guard.oxguardShardRead</source>
Optional read-only IP/name for Guest database shards that might be used in Master-Slave setups.

<source lang="bash">com.openexchange.guard.databaseUsername = username</source>
The username to access the OX Backend and Guard database. This user needs to have select, create, lock, insert, update privileges. Guard database user also should have alter (for updates), drop, index.

<source lang="bash">com.openexchange.guard.databasePassword = password</source>
The password for the databases

=== OX API ===

<source lang="bash">com.openexchange.guard.restApiHostname = localhost</source>
The address for the OX REST API. It would be the location of the OX Backend

<source lang="bash">com.openexchange.guard.OXBackendPort = 8009</source>
The port for the OX Backend. Default is 8009 (which is direct communication with the backend). Could be 80, etc, if going through load balancers

<source lang="bash">com.openexchange.guard.restApiUsername = open-xchange com.openexchange.guard.restApiPassword = secret</source>
Username and password for the REST API

<source lang="bash">com.openexchange.guard.externalEmailURL = example.com/appsuite/api/oxguard/reader/reader.html</source>
When Guard sends an encrypted eMail to members, they may not be using the webmail UI to read the email. A help file is attached, and a link will be provided to log into their webmail to read the encrypted item. This setting is used to point to a generic log in for the webmail system. Sent to multiple recipients, so not customized to the individual recipient.

=== Support API ===

<source lang="bash">com.openexchange.guard.supportapiusername = xxxxx
com.openexchange.guard.supportapipassword = yyyyy</source>
If the support API is to be used, a username and password should be configured.

<source lang="bash">com.openexchange.guard.exposedKeyDurationInHours = 168</source>
When a user is deleted, the Private keys are saved in a temporary deleted Keys table (in case of accidental deletion). If support "exposes" the key, the user can then retrieve it using link generated. For security reasons, this link is only valid for a short period of time. This property defines that duration.

=== File Storage ===

Local/remote storage is required for temporary caching of encrypted emails to guest/non-OX users. This can be an attached local file store, or Amazon S3 compatible object store depending on which <code>open-xchange-guard-*-storage</code> package is installed (<code>file</code> or <code>S3</code>).

==== General Properties ====

<source lang="bash">com.openexchange.guard.guestCleanedAfterDaysOfInactivity=365</source>
Specifies how long emails and guest accounts are maintained for guests that have not had any activity. If the guest has not logged into the Guest account in the configured time, the emails are removed and the Guest account is closed.

=== Storage Specific Properties ===

==== File-Storage ====

<source lang="bash">com.openexchange.guard.storage.file.uploadDirectory = /var/spool/open-xchange/guard/uploads</source>
Defines the temporary upload and cache directory for OX Guard Drive files for <code>open-xchange-guard-file-storage</code> package.
This directory needs to be shared between application servers serving the Guest Reader interface.

==== S3-Storage ====

<source lang="bash">com.openexchange.guard.storage.s3.endpoint =
com.openexchange.guard.storage.s3.bucketName =
com.openexchange.guard.storage.s3.region =
com.openexchange.guard.storage.s3.accessKey =
com.openexchange.guard.storage.s3.secretKey =</source>
S3 configuration options if the package <code>open-xchange-guard-s3-storage</code> is selected.

=== Crypto ===

<source lang="bash">com.openexchange.guard.aesKeyLength=256 (Depreciated)</source>
AES Key length. 256 is preferred, but not supported on all systems. May need to have the [http://www.oracle.com/technetwork/java/javase/downloads/index.html Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files] installed.

<source lang="bash">com.openexchange.guard.rsaKeyLength=2048</source>
RSA key length. Used when creating PGP keys

=== PGP ===

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
List of PGP Public key servers to query for public keys

<source lang="bash">com.openexchange.guard.publicKeyWhitelist</source>
A list of IP addresses of TRUSTED Guard servers. When the public PGP key server is queried, it will normally only find Guard keys that have already been created. If on the whitelist, the Guard server will also query the OX backend to see if the email address exists on the OX system, and if so, will create new keys for the user.

<source lang="bash">com.openexchange.guard.keyValidDays = 3650</source>
PGP keys created will only be valid for this number of days. Default is 10 years. Set to 0 if no expiration date.

<source lang="bash">com.openexchange.guard.pgpCacheDays=7</source>
When looking up remote PGP keys, if found, the keys will be stored in a temporary cache. Set number of days until the cache item is expired and remote lookup is repeated.

<pre>com.openexchange.guard.usestarttls = true</pre>
Use TLS when delivering to the SMTP server when available

=== Email ===

<source lang="bash">com.openexchange.guard.guestSMTPServer=smtp.example.com
com.openexchange.guard.guestSMTPPort=25
com.openexchange.guard.guestSMTPUsername=
com.openexchange.guard.guestSMTPPassword=</source>
SMTP settings for outgoing emails from the guest reader. Emails sent from within the system use the OX Backend. The guest reader, however, sends replies through this SMTP. In addition, password emails (reset, initial) are sent through the SMTP server.

=== Bad Attempts ===

<source lang="bash">com.openexchange.guard.badMinuteLock = 10</source>
Defines how long someone will be locked out after bad attempts. Defaults to 10 minutes.

<source lang="bash">com.openexchange.guard.badPasswordCount = 5</source>
Defines how many times a person can attempt to unlock an encrypted item before being locked out. Defaults to 5 times.

=== RSA Key Generation ===

<source lang="bash">com.openexchange.guard.rsacache = true</source>
RSA keys are pre-generated in the background, encrypted, and stored for future user keys. RSA key generation is the most time consuming function and the RSA cache significantly improves new user creation time.

<source lang="bash">com.openexchange.guard.rsacachecount = 100</source>
Number of RSA keys to pre-generate

<source lang="bash">com.openexchange.guard.keycachecheckinterval = 30</source>
Interval in seconds to check the RSA cache and re-populate if less than rsacachecount.

<source lang="bash">com.openexchange.guard.rsacertainty = 256</source>
Bit certainty for RSA key generation. Higher numbers assure the number is in fact prime but time consuming. Lower is much faster. May need to be lower if not using cache.

=== Passwords ===

<source lang="bash">com.openexchange.guard.newpasslength=8</source>
Length of the randomly generated passwords when a user resets password.

<source lang="bash">com.openexchange.guard.minpasswordlength=6</source>
Minimum password length.

=== Backend ===

<source lang="bash">com.openexchange.guard.oxbackendpath = /ajax/</source>
URL used to communicated directly with the OX backend.

<source lang="bash">com.openexchange.guard.oxbackendidletime = 60</source>
HTTP connections to the backend are kept open for faster response. This is the timeout setting that will close idle connections.

=== Guest Accounts ===

<source lang="bash">com.openexchange.guard.shardsize=1000</source>
Guest users data are placed in databases oxguard_x. After set number of users, another database shard is created

=== Recovery ===

If you do not want password recovery available, you can disable by adding

<source lang="bash">com.openexchange.guard.noRecovery = true</source>
Keep in mind, that a lost password will result in total loss of encrypted data.

=== Miscellaneous ===

<source lang="bash">com.openexchange.guard.secureReply = true</source>
(since Guard 2.2) Normally, when a person replies from an encrypted email, the reply is automatically encrypted. Set to false to disable this automatic encryption

== SSL ==

Starting with 2.4.0, OX Guard is running inside the OSGi container, meaning that all its servlets are being registered and served by Grizzly.

=== API SSL ===

<source lang="bash">com.openexchange.guard.backendSSL = false</source>
Per default the connection between the Guard backend and the configured Open-Xchange
REST API host is unencrypted. Even though that Guard will never transmit unencrypted
emails to or from the REST API you can optionally encrypt the whole communication between
those two components by using SSL. Please note: Enabling SSL might decrease performance
and/or create more system load due to additional encoding of the HTTP streams.

=== Incoming SSL ===

The communication between the frontend load balancer (Apache or otherwise) to Guard is by default HTTP (if protected network). More information on how to enable SSL you can find [http://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#X-FORWARDED-PROTO_Header here].

AppSuite:OX Guard Modular

2018-03-13T12:36:22Z

Greg.hill: /* Configuring key servers */

= Ox Guard Multi Node Setup =

== Overview ==

If there are multiple installations of Guard and OX backends some additional configuration may be required to maximize the user experience.

When a Guard email is sent to a user not local to the Guard installation (not a member of the local OX installation), then Guard takes the following steps

* Search for any keys available using configured key servers
* Search for SRV records containing PGP information
* If no keys found, then create a Guest account

A Guest account creates a pair of PGP Public/Private keys, and sends the user a link to read the email using Guard's Guest reader.

Ideally, if the recipient is in a Guard installation, they should receive an encrypted email using their Guard keys rather than a Guest account link. That way, the experience is the same for them regardless if they received an email from a local user, or an external Guard account.

== Configuring key servers ==

In the file /opt/open-xchange/etc/guard-core.properties file, there is a configuration setting

com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371

If you know of other Guard installations that your users will be using, then it should be added here. The URLs can follow the standard hkp://domain:11371, or can specify a more detailed URL. If a more detailed URL, then it should end with a "?" at which point the standard hkp parameters will be added. If just the domain is given, then the standard "/pks/lookup?" is used.

Guard servers, if addressed directly, should have the URL http://address:port/pgp/lookup?

For example, if you are addressing another Guard server (say 10.10.10.100 using port 8080) directly, you would use the URL

com.openexchange.guard.publicPGPDirectory = http://10.10.10.100:8080/pgp/lookup?

If, on the other hand, you are using an Apache front end load balancer as configured in the installation directions, the URL would be

com.openexchange.guard.publicPGPDirectory = http://frontend

== Key Generation ==

Guard creates user keys on demand. Key generation, on the other hand, is very CPU intensive. Therefore, the public key lookup service does not, by default, create keys for users.

So, if sending to a user in another Guard installation that has a Guard server, but the user hasn't setup keys, the public key server will return "No keys" for the user.

Again, this is less than ideal, as we would like that user to have the full UI experience. To work around this, Guard has a whitelist setting for known Guard servers

# Comma delim CDIR notation or distinct IP. eg "= 10.0.100.0/24, 192.168.10.3"
com.openexchange.guard.publicKeyWhitelist=

If the sending server is listed in this Whitelist, then the public key server WILL create keys for the user, and send that user a welcome message with a temporary password.

With the Whitelist parameter set, the experience for the sender and recipient is the same as if both users were local.

If there is a frontend used, the IP address of the sending Guard server might be masked, however. In this case, Guard respect the HTTP parameter "X-Forwarded-For"

== Testing ==

The response of a Guard server can be tested by using the URL

http://guardserver:8080/pgp/lookup?op=index&search=john@somewhere.com

Substitute the email address for a test user. If the user has set up keys already, their public keys will be listed. If they don't have keys yet, it will depend on the whitelist settings. If your computer is in the whitelist, then keys should be generated and the user should receive a welcome email.

Ideally, you should also check between two different nodes. Log into an account in node 1. Compose an email, enable encryption, then type the name of a user in node 2. A PGP key icon should appear next to the name if proper lookup done. If a "green man" icon appears, then a Guest account would be created and the key lookup failed.

== User Capabilities ==

We strongly encourage administrators to enable the capability

com.openexchange.capability.guard=true

for all users. This is the minimum Guard capability level. It allows the user to read an encrypted emails sent to them, and reply to those emails. This minimum level, though, does not allow the user to create new emails or encrypt files. We feel this is the best experience for the sender and recipients, and provides an excellent upsell opportunity.

AppSuite:OX Guard Upgrade 2 10

2018-03-12T17:13:30Z

Greg.hill: Initial 2.10 upgrade documentation

= Upgrading OX Guard to 2.10 from 2.6/2.8 =

== Introduction ==

With '''OX Guard 2.10.0''' the experience for external recipients has changed significantly. Pre 2.10, there was a guest reader HTML package that allowed recipients to decrypt and reply to PGP emails. This has now changed. External recipients now have an Appsuite Guest account created, similar to a file share, with an pseudo inbox that lists all of the encrypted emails sent to them. The recipient will still be able to reply to emails sent to them, but will not be able to create new emails.

Bringing external users into Appsuite presents additional upsell opportunity as well as advertising options.

== Changes ==

This section covers the changes introduced with OX Guard 2.10.0.

=== Guest Users ===

All Guest users must have guard capability in order to read encrypted emails. To do this, the following configuration file <code>/opt/open-xchange/etc/share.properties</code> needs to be modified.

Assuming the guestCapabilityMode is set to static, please add guard to the staticGuestCapabilities

com.openexchange.share.guestCapabilityMode=static
com.openexchange.share.staticGuestCapabilities=guard

=== WebKey Service ===

Optional WebKey server was added in 2.10. This allows external users to look up the public PGP keys of Guard users as described [https://tools.ietf.org/html/draft-koch-openpgp-webkey-service-02 here]. To enable this ability, an additional ProxyPass needs to be added to the proxy_http.conf file

ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu

=== Reader Package ===

The package com.openexchange.guard.reader is no longer required, but recommended for those upgrading from an earlier version.
The package no longer contains a full guest reader, rather it redirects old Guard guest share links to the new appsuite guest. This package will be required for as long as old guest emails should remain functional.

=== Configuration Changes ===

==== Guest Configuration ====

Encrypted emails sent to external recipients was previously cached for a period of time, defaulting to 90 days. After this time, the reader would not function unless the user uploaded the attachment sent with their emails.

This has changed in 2.10. Now, a Guest user has a virtual inbox, listing the encrypted emails sent to them. A new configuration setting has been added

com.openexchange.guard.guestCleanedAfterDaysOfInactivity=365

This configuration cleans up a Guest account after the configured number of days if the user has not logged in. All emails for the guest account will be purged, and the Guest accounts removed from appsuite. A setting of 0 disables the cleaning completely.

==== Trust Levels ====

Some PGP Public keys can be trusted more than others. Guard now displays if the key is trusted or not by changing the color of the key next to a recipients email address, and provides details if the user hovers over the key. The trust level can be configured in the guard-core.properties file

com.openexchange.guard.keySources.trustThreshold=4
# The trust level for keys created by OX Guard
com.openexchange.guard.keySources.trustLevelGuard=5
# The trust level for keys uploaded by a user
com.openexchange.guard.keySources.trustLevelGuardUserUploaded=4
# The trust level for keys uploaded by a user and shared among users in the same context
com.openexchange.guard.keySources.trustLevelGuardUserShared=3
# The trust level for keys fetched from public HKP servers
com.openexchange.guard.keySources.trustLevelHKPPublicServer=1
# The trust level for keys fetched from HKP servers marked as trusted
com.openexchange.guard.keySources.trustLevelHKPTrustedServer=5
# The trust level for keys fetched from HKP servers queried via SRV DNS record
com.openexchange.guard.keySources.trustLevelHKPSRVServer=4
# The trust level for keys fetched from HKP servers queried via DNSSEC protected SRV DNS record
com.openexchange.guard.keySources.trustLevelHKPSRVDNSSECServer=4

AppSuite:OX Guard

2018-01-19T15:02:07Z

Greg.hill: /* Support API */

AppSuite:GuardCustomization

2017-08-24T15:03:44Z

Greg.hill: /* Emails */

= Ox Guard Customization =

== Overview ==
Guard uses several templates for emails and the Guest reader. These templates are fully customizable, and can be customized at the global level, but also at the context/user level. Changing images, colors, and layout is easy. Changing the wording is also possible, though the translation tables will then need to be updated.

== Template ID ==
Guard uses a template ID for choosing the templates to use. The template ID can be chosen for a user or context using the configuration cascade.

com.openexchange.guard.templateID=x

For any template below, a customized template can be created with the name x-templatename where x is the integer value of the template ID for the user. For example, if you wanted a custom password template based on the template "passwordtempl.html" for a context of users, you could create a template "2-passwordtempl.html" and assign the value com.openexchange.guard.templateID=2 to the context. Then, Guard will use any templates that start with "2-" for the context.

'''NOTE:'''
If no template ID is specified, or if a file specified by the template ID is not found, then the default template is used. The default is the templates with no number prefix, i.e. "passwordtempl.html"

== Templates ==
=== Emails ===
* guesttempl.html - Email template used when sending to a guest user (not an OX account)
* passwordtempl.html - Template used to send a new password to a guest user. As of 2.8, only used if newGuestsRequirePassword=true is configured
* oxpasswordtempl.html - Email template used when sending a new password to an OX user. No longer used after 2.6
* resettempl.html - Template used when sending a password reset
* guestresettempl.html - Template used when resetting guest account

=== Guest Reader ===
* reader.html - The main guest reader template. THIS IS NOT CUSTOMIZABLE WITH TEMPLATE ID. GLOBAL CHANGES ONLY. We recommend not changing this file and using the header, footer, and style sheets for branding.
* header.html - Top header bar of the Guest reader
* footer.html - Footer of the Guest reader
* style.css - Style sheet for the Guest reader

== Email Template GetText ==
In the HTML templates, wording is surrounded by a call to gettext, which will get the translation for the user. It is used in a HTML call <$gettext("text here")>
Example:

<$gettext("You have received this email because $from has sent you a secure email message with OX Guard. You will receive a link to the secure message in a separate email.")>

== Variables ==
Some email templates have space for variables depending on their function. The variable name will begin with $ such as the above example $from.

== Guest Reader Translations ==
The Guest reader webpage uses i18next for translations. If changing the header and footer such that you need translation, use a call such as

<h2 data-i18n="PIN Required:">PIN Required:</h2>

The "data-i18n" property results in the inner HTML wording being replaced with the translation (if available for the specified language)

=====Guest Translations as of Version 2.4.2-rev8=====
Custom Guest reader translations can be managed by creating a file custom-Lang.json located in the /var/www/html/reader/l10n (on Debian 8)
This custom file should contain only the translations you want to replace in the default translation-Lang.json files.

For example, if you wanted to change the French translation of
"Welcome" from "Bienvenue" to "Bonjour", you would create a file custom-FR_fr.json with the contents

<code>
{
"Welcome" : "Bonjour"
}
</code>

The reader will load the file translations-FR_fr.json first, then it will load custom and overwrite any values found.

= Guard Product Name Customization (2.4 or 2.2.1-8+) =

== Overview ==

The Guard product name can be configured by general setting for smaller deployments, by configuration cascade, or by URL

== Product name by configuration ==

The configuration
com.openexchange.guard.productName
can be defined in the guard-core.properties (2.4) or in the guard.properties file (2.2.1-8). This product name will be passed to the UI.

This value can also be configured at the configuration cascade level

== Product name by URL ==

By editing the file yml located in /opt/open-xchange/etc/as-config.yml the property
guard.productName
can be defined based on the browser URL/IP used to address the OX backend. This product name will the be passed to the UI to be displayed by the user.

AppSuite:OX Guard

2017-03-21T13:15:44Z

Greg.hill: /* Reset password */

= OX Guard (Version 2.4+ )=

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|}

=== Important Notes ===

==== Customisation ====

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 Customisation] 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:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code>

The components required for the OX frontend are: <code>open-xchange-guard-ui</code> <code>open-xchange-guard-ui-static</code> <code>open-xchange-guard-reader</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files)

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 7.0 (Wheezy) (valid until v2.4.2) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/2.4.2/guard/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/7.8.2/backend/DebianWheezy /</source>

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 open-xchange-guard-reader</source>

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storagec</source>

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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>

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 open-xchange-guard-reader</source>

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== RedHat Enterprise Linux 6 or CentOS 6 ===

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/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

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 open-xchange-guard-reader</source>
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> 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</source>

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</source>
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>

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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 11 (valid until v2.4.2) ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/2.4.2/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/7.8.2/backend/SLES11 ox-backend</source>

and then run for a single node installation:

$ zypper ref
$ zypper in 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefore we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</source>

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-reader</source>

or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>

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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</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 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) (valid until v2.4.2) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.4.2/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.8.2/backend/DebianWheezy /</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 8.0 (Jessie) ===

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/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</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 6 or CentOS 6 ===

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/RHEL6/
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/RHEL6/
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 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>

=== SUSE Linux Enterprise Server 11 (valid until v2.4.2) ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.4.2/guard/updates/SLES11 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.8.2/backend/updates/SLES11 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== 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.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><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</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> 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 BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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 starting the initialization. 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</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.

'''Guard Mail''' and '''Guard Drive''' 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.

Each of those two 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 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>
==== Guard Drive: ====

<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 bakend.

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>
==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><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.
ProxyPass /preliminary balancer://oxcluster/preliminary
</Location></source>
Make sure that the balancer is properly configured in the <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>
==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== 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.properties file using the following settings:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportapiusername=
com.openexchange.guard.supportapipassword=</source>
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 ===

<code>POST /guardsupport/?action=reset_password</code>

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:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (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 ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard

2017-03-21T12:39:10Z

Greg.hill: /* Reset password */

= OX Guard (Version 2.4+ )=

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|}

=== Important Notes ===

==== Customisation ====

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 Customisation] 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:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code>

The components required for the OX frontend are: <code>open-xchange-guard-ui</code> <code>open-xchange-guard-ui-static</code> <code>open-xchange-guard-reader</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files)

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 7.0 (Wheezy) (valid until v2.4.2) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/2.4.2/guard/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/7.8.2/backend/DebianWheezy /</source>

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 open-xchange-guard-reader</source>

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storagec</source>

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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>

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 open-xchange-guard-reader</source>

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== RedHat Enterprise Linux 6 or CentOS 6 ===

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/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

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 open-xchange-guard-reader</source>
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> 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</source>

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</source>
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>

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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 11 (valid until v2.4.2) ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/2.4.2/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/7.8.2/backend/SLES11 ox-backend</source>

and then run for a single node installation:

$ zypper ref
$ zypper in 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefore we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</source>

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-reader</source>

or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>

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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</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 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) (valid until v2.4.2) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.4.2/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.8.2/backend/DebianWheezy /</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 8.0 (Jessie) ===

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/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</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 6 or CentOS 6 ===

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/RHEL6/
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/RHEL6/
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 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>

=== SUSE Linux Enterprise Server 11 (valid until v2.4.2) ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.4.2/guard/updates/SLES11 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.8.2/backend/updates/SLES11 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== 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.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><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</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> 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 BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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 starting the initialization. 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</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.

'''Guard Mail''' and '''Guard Drive''' 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.

Each of those two 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 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>
==== Guard Drive: ====

<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 bakend.

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>
==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><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.
ProxyPass /preliminary balancer://oxcluster/preliminary
</Location></source>
Make sure that the balancer is properly configured in the <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>
==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== 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.properties file using the following settings:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportapiusername=
com.openexchange.guard.supportapipassword=</source>
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 ===

<code>POST /guardsupport/?action=reset_password</code>

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:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:GuardCustomization

2016-11-10T18:12:36Z

Greg.hill: /* Guest Reader Translations */

= Ox Guard Customization =

== Overview ==
Guard uses several templates for emails and the Guest reader. These templates are fully customizable, and can be customized at the global level, but also at the context/user level. Changing images, colors, and layout is easy. Changing the wording is also possible, though the translation tables will then need to be updated.

== Template ID ==
Guard uses a template ID for choosing the templates to use. The template ID can be chosen for a user or context using the configuration cascade.

com.openexchange.guard.templateID=x

For any template below, a customized template can be created with the name x-templatename where x is the integer value of the template ID for the user. For example, if you wanted a custom password template based on the template "passwordtempl.html" for a context of users, you could create a template "2-passwordtempl.html" and assign the value com.openexchange.guard.templateID=2 to the context. Then, Guard will use any templates that start with "2-" for the context.

'''NOTE:'''
If no template ID is specified, or if a file specified by the template ID is not found, then the default template is used. The default is the templates with no number prefix, i.e. "passwordtempl.html"

== Templates ==
=== Emails ===
* guesttempl.html - Email template used when sending to a guest user (not an OX account)
* passwordtempl.html - Template used to send a new password to a guest user
* oxpasswordtempl.html - Email template used when sending a new password to an OX user
* resettempl.html - Template used when sending a password reset
* oxtempl.html - Template used in Guard 1.2. Depreciated in 2.0

=== Guest Reader ===
* reader.html - The main guest reader template. THIS IS NOT CUSTOMIZABLE WITH TEMPLATE ID. GLOBAL CHANGES ONLY. We recommend not changing this file and using the header, footer, and style sheets for branding.
* header.html - Top header bar of the Guest reader
* footer.html - Footer of the Guest reader
* style.css - Style sheet for the Guest reader

== Email Template GetText ==
In the HTML templates, wording is surrounded by a call to gettext, which will get the translation for the user. It is used in a HTML call <$gettext("text here")>
Example:

<$gettext("You have received this email because $from has sent you a secure email message with OX Guard. You will receive a link to the secure message in a separate email.")>

== Variables ==
Some email templates have space for variables depending on their function. The variable name will begin with $ such as the above example $from.

== Guest Reader Translations ==
The Guest reader webpage uses i18next for translations. If changing the header and footer such that you need translation, use a call such as

<h2 data-i18n="PIN Required:">PIN Required:</h2>

The "data-i18n" property results in the inner HTML wording being replaced with the translation (if available for the specified language)

=====Guest Translations as of Version 2.4.2-rev8=====
Custom Guest reader translations can be managed by creating a file custom-Lang.json located in the /var/www/html/reader/l10n (on Debian 8)
This custom file should contain only the translations you want to replace in the default translation-Lang.json files.

For example, if you wanted to change the French translation of
"Welcome" from "Bienvenue" to "Bonjour", you would create a file custom-FR_fr.json with the contents

<code>
{
"Welcome" : "Bonjour"
}
</code>

The reader will load the file translations-FR_fr.json first, then it will load custom and overwrite any values found.

= Guard Product Name Customization (2.4 or 2.2.1-8+) =

== Overview ==

The Guard product name can be configured by general setting for smaller deployments, by configuration cascade, or by URL

== Product name by configuration ==

The configuration
com.openexchange.guard.productName
can be defined in the guard-core.properties (2.4) or in the guard.properties file (2.2.1-8). This product name will be passed to the UI.

This value can also be configured at the configuration cascade level

== Product name by URL ==

By editing the file yml located in /opt/open-xchange/etc/as-config.yml the property
guard.productName
can be defined based on the browser URL/IP used to address the OX backend. This product name will the be passed to the UI to be displayed by the user.

AppSuite:OX Guard

2016-11-10T18:02:15Z

Greg.hill: /* Download and Installation */

= OX Guard (Version 2.4+ )=

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|}

=== Important Notes ===

==== Customisation ====

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 Customisation] 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:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code>

The components required for the OX frontend are: <code>open-xchange-guard-ui</code> <code>open-xchange-guard-ui-static</code> <code>open-xchange-guard-reader</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files)

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 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
and then run for a single node installation:

<source lang="bash">$ 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storagec</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
and then run for a single node installation:

<source lang="bash">$ 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== RedHat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run for a single node installation:

<source lang="bash">$ 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> 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:

<source lang="bash">[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</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 11 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLES11 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefore we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</source>

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage</source>
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 packages <code>open-xchange-guard-ui-static</code> and <code>open-xchange-guard-reader</code> must be installed in the frontend (apache node).

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</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 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Redhat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== SUSE Linux Enterprise Server 11 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLES11 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLES11 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== 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.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><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</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> 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 BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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 starting the initialization. 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</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.

'''Guard Mail''' and '''Guard Drive''' 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.

Each of those two 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 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>
==== Guard Drive: ====

<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 bakend.

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>
==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><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.
ProxyPass /preliminary balancer://oxcluster/preliminary
</Location></source>
Make sure that the balancer is properly configured in the <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>
==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== 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.properties file using the following settings:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportapiusername=
com.openexchange.guard.supportapipassword=</source>
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 ===

<code>POST /guardsupport/?action=reset_password</code>

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. The reset password function is currently not available for guest users. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard

2016-11-10T17:55:17Z

Greg.hill: /* SUSE Linux Enterprise Server 12 */

= OX Guard (Version 2.4+ )=

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|}

=== Important Notes ===

==== Customisation ====

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 Customisation] 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:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-rest</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code>

The components required for the OX frontend are: <code>open-xchange-guard-ui</code> <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files)

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 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
and then run for a single node installation:

<source lang="bash">$ 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
and then run for a single node installation:

<source lang="bash">$ 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== RedHat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run for a single node installation:

<source lang="bash">$ 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== SUSE Linux Enterprise Server 11 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLES11 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefore we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</source>

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</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 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>
== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Redhat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== SUSE Linux Enterprise Server 11 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLES11 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLES11 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== 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.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><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</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> 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 BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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 starting the initialization. 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</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.

'''Guard Mail''' and '''Guard Drive''' 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.

Each of those two 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 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>
==== Guard Drive: ====

<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 bakend.

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>
==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><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.
ProxyPass /preliminary balancer://oxcluster/preliminary
</Location></source>
Make sure that the balancer is properly configured in the <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>
==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== 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.properties file using the following settings:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportapiusername=
com.openexchange.guard.supportapipassword=</source>
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 ===

<code>POST /guardsupport/?action=reset_password</code>

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. The reset password function is currently not available for guest users. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard

2016-11-10T17:54:58Z

Greg.hill: /* SUSE Linux Enterprise Server 11 */

= OX Guard (Version 2.4+ )=

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|}

=== Important Notes ===

==== Customisation ====

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 Customisation] 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:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-rest</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code>

The components required for the OX frontend are: <code>open-xchange-guard-ui</code> <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files)

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 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
and then run for a single node installation:

<source lang="bash">$ 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
and then run for a single node installation:

<source lang="bash">$ 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== RedHat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run for a single node installation:

<source lang="bash">$ 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== SUSE Linux Enterprise Server 11 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLES11 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefore we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</source>

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</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 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>
== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Redhat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== SUSE Linux Enterprise Server 11 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLES11 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLES11 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== 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.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><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</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> 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 BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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 starting the initialization. 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</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.

'''Guard Mail''' and '''Guard Drive''' 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.

Each of those two 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 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>
==== Guard Drive: ====

<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 bakend.

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>
==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><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.
ProxyPass /preliminary balancer://oxcluster/preliminary
</Location></source>
Make sure that the balancer is properly configured in the <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>
==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== 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.properties file using the following settings:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportapiusername=
com.openexchange.guard.supportapipassword=</source>
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 ===

<code>POST /guardsupport/?action=reset_password</code>

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. The reset password function is currently not available for guest users. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard

2016-11-10T17:54:40Z

Greg.hill: /* RedHat Enterprise Linux 6 or CentOS 6 */

= OX Guard (Version 2.4+ )=

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|}

=== Important Notes ===

==== Customisation ====

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 Customisation] 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:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-rest</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code>

The components required for the OX frontend are: <code>open-xchange-guard-ui</code> <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files)

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 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
and then run for a single node installation:

<source lang="bash">$ 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
and then run for a single node installation:

<source lang="bash">$ 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== RedHat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run for a single node installation:

<source lang="bash">$ 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== SUSE Linux Enterprise Server 11 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLES11 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in 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</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefore we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</source>
=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</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 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>
== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Redhat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== SUSE Linux Enterprise Server 11 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLES11 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLES11 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== 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.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><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</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> 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 BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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 starting the initialization. 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</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.

'''Guard Mail''' and '''Guard Drive''' 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.

Each of those two 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 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>
==== Guard Drive: ====

<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 bakend.

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>
==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><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.
ProxyPass /preliminary balancer://oxcluster/preliminary
</Location></source>
Make sure that the balancer is properly configured in the <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>
==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== 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.properties file using the following settings:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportapiusername=
com.openexchange.guard.supportapipassword=</source>
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 ===

<code>POST /guardsupport/?action=reset_password</code>

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. The reset password function is currently not available for guest users. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard

2016-11-10T17:54:23Z

Greg.hill: /* Debian Linux 8.0 (Jessie) */

= OX Guard (Version 2.4+ )=

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|}

=== Important Notes ===

==== Customisation ====

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 Customisation] 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:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-rest</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code>

The components required for the OX frontend are: <code>open-xchange-guard-ui</code> <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files)

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 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
and then run for a single node installation:

<source lang="bash">$ 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
and then run for a single node installation:

<source lang="bash">$ 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== RedHat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== SUSE Linux Enterprise Server 11 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLES11 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in 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</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefore we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</source>
=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</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 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>
== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Redhat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== SUSE Linux Enterprise Server 11 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLES11 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLES11 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== 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.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><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</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> 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 BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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 starting the initialization. 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</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.

'''Guard Mail''' and '''Guard Drive''' 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.

Each of those two 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 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>
==== Guard Drive: ====

<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 bakend.

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>
==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><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.
ProxyPass /preliminary balancer://oxcluster/preliminary
</Location></source>
Make sure that the balancer is properly configured in the <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>
==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== 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.properties file using the following settings:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportapiusername=
com.openexchange.guard.supportapipassword=</source>
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 ===

<code>POST /guardsupport/?action=reset_password</code>

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. The reset password function is currently not available for guest users. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard

2016-11-10T17:54:09Z

Greg.hill: /* Debian Linux 7.0 (Wheezy) */

= OX Guard (Version 2.4+ )=

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|}

=== Important Notes ===

==== Customisation ====

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 Customisation] 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:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-rest</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code>

The components required for the OX frontend are: <code>open-xchange-guard-ui</code> <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files)

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 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
and then run for a single node installation:

<source lang="bash">$ 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 open-xchange-guard-reader</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== RedHat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== SUSE Linux Enterprise Server 11 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLES11 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in 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</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefore we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</source>
=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</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 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>
== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Redhat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== SUSE Linux Enterprise Server 11 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLES11 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLES11 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== 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.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><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</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> 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 BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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 starting the initialization. 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</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.

'''Guard Mail''' and '''Guard Drive''' 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.

Each of those two 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 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>
==== Guard Drive: ====

<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 bakend.

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>
==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><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.
ProxyPass /preliminary balancer://oxcluster/preliminary
</Location></source>
Make sure that the balancer is properly configured in the <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>
==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== 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.properties file using the following settings:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportapiusername=
com.openexchange.guard.supportapipassword=</source>
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 ===

<code>POST /guardsupport/?action=reset_password</code>

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. The reset password function is currently not available for guest users. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard

2016-11-10T17:52:28Z

Greg.hill: /* Mail Resolver */

= OX Guard (Version 2.4+ )=

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|}

=== Important Notes ===

==== Customisation ====

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 Customisation] 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:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-rest</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code>

The components required for the OX frontend are: <code>open-xchange-guard-ui</code> <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files)

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 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== RedHat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== SUSE Linux Enterprise Server 11 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLES11 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in 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</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefore we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</source>
=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</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 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>
== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Redhat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== SUSE Linux Enterprise Server 11 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLES11 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLES11 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== 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.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><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</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> 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 BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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 starting the initialization. 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</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.

'''Guard Mail''' and '''Guard Drive''' 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.

Each of those two 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 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>
==== Guard Drive: ====

<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 bakend.

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>
==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><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.
ProxyPass /preliminary balancer://oxcluster/preliminary
</Location></source>
Make sure that the balancer is properly configured in the <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>
==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== 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.properties file using the following settings:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportapiusername=
com.openexchange.guard.supportapipassword=</source>
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 ===

<code>POST /guardsupport/?action=reset_password</code>

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. The reset password function is currently not available for guest users. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard

2016-11-10T17:50:47Z

Greg.hill: /* Requirements */

= OX Guard (Version 2.4+ )=

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|}

=== Important Notes ===

==== Customisation ====

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 Customisation] 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.

Be sure to test the mail resolver using:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-rest</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code>

The components required for the OX frontend are: <code>open-xchange-guard-ui</code> <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files)

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 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== RedHat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== SUSE Linux Enterprise Server 11 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLES11 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in 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</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefore we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</source>
=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</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 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>
== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Redhat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== SUSE Linux Enterprise Server 11 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLES11 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLES11 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== 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.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><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</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> 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 BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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 starting the initialization. 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</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.

'''Guard Mail''' and '''Guard Drive''' 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.

Each of those two 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 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>
==== Guard Drive: ====

<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 bakend.

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>
==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><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.
ProxyPass /preliminary balancer://oxcluster/preliminary
</Location></source>
Make sure that the balancer is properly configured in the <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>
==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== 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.properties file using the following settings:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportapiusername=
com.openexchange.guard.supportapipassword=</source>
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 ===

<code>POST /guardsupport/?action=reset_password</code>

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. The reset password function is currently not available for guest users. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard

2016-05-04T12:39:11Z

Greg.hill: /* Support API */

= OX Guard (Version 2.4+ )=

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

=== Important Notes ===

==== Customisation ====

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 Customisation] 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.

Be sure to test the mail resolver using:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-rest</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code>

The components required for the OX frontend are: <code>open-xchange-guard-ui</code> <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files)

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 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== RedHat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== SUSE Linux Enterprise Server 11 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLES11 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in 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</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefore we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</source>
=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</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 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>
== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Redhat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== SUSE Linux Enterprise Server 11 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLES11 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLES11 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== 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.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><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</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> 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 BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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 starting the initialization. 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</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.

'''Guard Mail''' and '''Guard Drive''' 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.

Each of those two 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 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>
==== Guard Drive: ====

<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 bakend.

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>
==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><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.
ProxyPass /preliminary balancer://oxcluster/preliminary
</Location></source>
Make sure that the balancer is properly configured in the <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>
==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== 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.properties file using the following settings:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportapiusername=
com.openexchange.guard.supportapipassword=</source>
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 ===

<code>POST /guardsupport/?action=reset_password</code>

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. The reset password function is currently not available for guest users. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard Upgrade OSGI

2016-04-01T18:15:38Z

Greg.hill: /* Step 6 - Ensure that the Apache balancer directive uses the correct port */

= Upgrading OX Guard from 2.2.x to 2.4.0 =

== Introduction ==

With '''OX Guard 2.4.0''' the first step was made and the product was moved into the OSGi stack. Although OX Guard now has a tighter integration with the core that does not mean that it lost its micro-service character. OX Guard still relies on the support API to accomplish its tasks; tasks like capability check, HTML sanitising and mail address resolving. The database calls however were completely eliminated (along with their support API) and now the core's OSGi services are used for that purpose. The same applies to the configuration.

In the next few sections it is described what was changed and the necessary steps to upgrade from 2.2.x to 2.4.0. For a fresh installation refer to the main [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard OX Guard] article.

== Changes ==

This section covers the changes introduced with OX Guard 2.4.0.

=== Configuration Structure ===

Alongside with the OSGi-fication of the product, a bit of clean up took place, regarding the configuration files and their structure.

The most obvious change was to get rid of the separate <code>/opt/open-xchange/guard</code> directory that the entire configuration was residing in. The contents of this directory are now spread accross the appropriate folders in <code>/opt/open-xchange</code>.

==== Templates ====

The templates (originally located under <code>/opt/open-xchange/guard/templates</code>) were moved to the <code>templates</code> directory of the open-xchange installation, i.e. to <code>/opt/open-xchange/templates/guard</code>.

==== Translations ====

The translations (originally located under <code>/opt/open-xchange/guard/l10n</code>) were moved to the <code>i18n</code> directory of the open-xchange installation, i.e. to <code>/opt/open-xchange/i18n</code>. The translations formerly had a prefix <code>main-*_*.po</code> (i.e. <code>main-de_DE.po</code>) should now start with <code>guard-</code> (i.e. <code>guard-de_DE.po</code>) to be able to differentiate between middleware translations and those provided by OX Guard. Even the <code>languages.xml</code> and those starting with <code>templates-*</code> should be located within the above mentioned <code>i18n</code> directory.

==== Properties ====

===== guard.properties =====

Prior to 2.4.0, there were two <code>guard.properties</code> files, one for the core groupware which contained properties that were used to enable the OX Guard capability to various modules as well as some extra functionality, and one for OX Guard itself, containing all properties for that product. Since the <code>/opt/open-xchange/guard</code> directory was deemed obsolete and subject to be removed and to avoid the name clashing of the two property files, they had to be renamed. A merge was not option, simply because they were provided and used by different packages. Therefore, the properties file <code>guard.properties</code> (under <code>/opt/open-xchange/etc/</code>) which accomodated the properties for the AppSuite Guard bundle is now renamed to <code>guard-api.properties</code>.

The OX Guard <code>guard.properties</code> file (under <code>/opt/open-xchange/guard/etc</code>) which housed all the OX Guard properties, is now renamed and moved under <code>/opt/open-xchange/guard/etc/guard-core.properties</code>.

===== private_dns_key and public_dns_key =====

Those two property files were not needed anymore, thus they were marked as obsolete and removed with OX Guard 2.4.0.

=== Farewell Jetty, welcome Grizzly ===

With the big step OX Guard took and moved into the OSGi stack, Jetty was rendered obsolete and had to be removed as well. OX Guard now uses [https://grizzly.java.net/ Grizzly] to register its servlets.

=== Apache ===

The first change in the Apache configuration is the port number of the balancer directive regarding OX Guard. Since Jetty was removed and Grizzly is in charge now, the port was adjusted to reflect that change.

The second change is the order of the ProxyPass locations. The OX Guard one, had to be moved forward because it was getting masked and overwritten by the AppSuite ones.

=== Guest Reader moved to a separate package ===

In order to allow more flexibility on distributed deployments, the "Guest Reader" component has moved to a separate package that is being installed on the frontend server. The UI is then provided by Apache rather than Jetty.

Because of this, the location of the Guest reader URL will change. By default, the reader package will be installed under /var/www/guard/reader

So, in most setups, the reader URL would change from

domain/appsuite/api/oxguard/reader/reader.html?....

to

domain/guard/reader/reader.html?....

To handle this change, the easiest thing to do is change the externalReaderPath configuration in the new guard-core.proprties file from the old location to the new

com.openexchange.guard.externalReaderPath=domain/guard/reader/reader.html

Assuming that there are already several Guest emails out there with the old Jetty URL, Guard OSGI will automatically redirect all requests from the old location to the new

=== Command Line Tool ===

The command line tool also got a "lifting" and was brought to the standards of the rest of the command line tools of the OX family. The CLT now includes optional JMX authentication. Furthermore, the functionality of initialising the OX Guard installation was removed from the command line tool. It is now being done automatically upon server start up. The rest of the functionality is still there, though.

<pre>usage: guard [-i [-d /custom/path]] [-t john.doe@example.com] [-u
joan.doe@ox.io] [-e john.doe@example.com] [-n
joan.doe@example.com] [-j jmxUser] [-w jmxPassword] [-x
jmx.host] [-o <JMX_PORT>] [-p <RMI_PORT>] [--responsetimeout
<TIMEOUT>]
-d,--directory <arg> Full path of the 'oxguardpass' file
(defaults to current directory). This flag
should be used in conjunction with the
'--init' switch.
e.g. guard --init --directory
/opt/open-xchange/etc
-e,--reset <arg> Resets the specified e-mail address and
sends a new password to the user
e.g. guard --reset john@somewhere.com
-h,--help Prints a help text
-i,--init Initialise guard.
-j,--jmx-user <arg> JMX user
-n,--remove-pin <arg> Removes the PIN for the specified user
e.g. guard --remove-pin john@somewhere.com
-o,--jmx-port <arg> JMX port (default: '9999')
-p,--port <arg> The optional RMI port (default:1099)
--responsetimeout <arg> The optional response timeout in seconds
when reading data from server (default: 0s;
infinite)
-s,--server <arg> The optional RMI server (default: localhost)
-t,--test <arg> Test the specified e-mail address against
the MailResolver
e.g. guard --test john@somewhere.com
-u,--upgrade <arg> Upgrades the specified guest account to an
OX account
e.g. guard --upgrade john@somewhere.com
-w,--jmx-password <arg> JMX password
-x,--jmx-host <arg> JMX host (default: 'localhost')

Command line tool for OX Guard</pre>
=== Logging ===

The <code>/opt/open-xchange/guard/etc/logback.xml</code> file for OX Guard was completely removed. Now logging is being configured globally in <code>/opt/open-xchange/etc/logback.xml</code>. All OX Guard events that were previously logged in <code>/var/log/open-xchange/guard/guard.log</code> are now being logged in the log file as the groupware, namely in <code>/var/log/open-xchange/open-xchange.log.0</code>.

The SMTP relevant section is no longer present, but it can be configured separately by adding it again to the previous mentioned <code>logback.xml</code> file.

<source lang="xml">
<appender name="SMTP" class="ch.qos.logback.classic.net.SMTPAppender">
<smtpHost>smtphost</smtpHost>
<to>user@admin</to>
<from>notify@admin</from>
<subject>Guard - %marker - %msg%n </subject>
<layout class="ch.qos.logback.classic.html.HTMLLayout">
<pattern>%date%level%logger{24}%msg</pattern>
</layout>

<evaluator class="ch.qos.logback.classic.boolex.JaninoEventEvaluator">
<expression>
marker != null && (marker.contains("NOTIFY_MAJOR") || marker.contains("NOTIFY_MINOR"))
</expression>
</evaluator>
</appender></source>
The following tag has to be added to the <code>root</code> level in order for this to work.

<source lang="xml"><appender-ref ref="SMTP" /></source>
For example:

<source lang="xml"><root level="INFO">
<appender-ref ref="ASYNC"/>
<appender-ref ref="SMTP" />
</root></source>

== Upgrading from 2.2.x to 2.4.0 ==

There are a few things to consider when upgrading from a version 2.2.x to 2.4.0. In this section we will cover that upgrade path.

The first thing is that the file storage implementations are now being kept into two separate packages, i.e. <code>open-xchange-guard-file-storage</code> and <code>open-xchange-guard-s3-storage</code> for the file storage and S3 storage support respectively. This means that one of the packages has to be manually installed after the upgrade.

The second thing is that the <code>open-xchange-guard</code> system service is now gone. Since, OX Guard is intergraded into the OSGi stack, it will start automatically with the backend, i.e. when the <code>open-xchange</code> system service starts.

With those two things in mind, OX Guard can be upgraded as described [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard#Update_OX_Guard here]. Again, after the upgrade is complete there is no need to restart the <code>open-xchange-guard</code> system service; neither the <code>open-xchange</code> system service should be restarted just yet. There are a few things to do before having a fully functional OX Guard backend.

The Guest Reader component has moved to the <code>open-xchange-guard-reader</code> package, which needs to be installed on the frontend server next to App Suite UI.

=== Step 1 - Enhance repository sources ===

If you currently do not have an Open-Xchange middleware installed you have to adapt your Open-Xchange repository file to be able to solve required dependencies to the middleware packages. Add the following to the file that already should contain an entry for the OX Guard repository.

===== Debian 7.x =====

<source lang="bash">deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
===== Debian 8.x =====

<source lang="bash">deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
===== RedHat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
===== Redhat Enterprise Linux 7 or CentOS 7 =====

<source lang="bash">[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</source>
===== SUSE Linux Enterprise Server 11.x =====

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLES11 ox-backend</source>
===== SUSE Linux Enterprise Server 12.x =====

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>
After adding new repositories retrieve new lists of packages by executing your desired package managers update call.

=== Step 2 - Update OX Guard ===

Upgrade the existing installation by executing your desired package mangers upgrade call, for instance <code>apt-get dist-upgrade</code>, <code>yum upgrade</code> and so on.

If you are running an '''OX Guard-only node''' (because of infelicitous set dependencies) you have to install an implementation of the package <code>open-xchange-authentication</code> and <code>open-xchange-spamhandler</code> which will never be used but checked for. We suggest to install <code>open-xchange-authentication-database</code> and <code>open-xchange-spamhandler-default</code>. Installing those packages as well as chosing a <code>open-xchange-guard-storage</code> implementation will install all required middleware dependencies.

After the update <code>/etc/init.d/open-xchange-guard</code> shouldn't be available any more but OX Guard will start when starting the <code>open-xchange</code> system service.

=== Step 3 - Choose and install your storage ===

According to your previous installation, you will have to manually install the relevant <code>open-xchange-guard-storage</code> package. Of course, you can switch to the one or the other storage if you wish, but be aware that '''no data''' will be migrated. You will have to do this manually.

==== File Storage Support ====

If you want the file storage support, and depending on your Linux distribution, you can install it with the following command:

===== Debian 7.x/8.x =====

<source lang="bash">apt-get install open-xchange-guard-file-storage</source>
===== RedHat Enterprise Linux 6.x/7.x or CentOS 6.x/7.x =====

<source lang="bash">yum install open-xchange-guard-file-storage</source>
===== SUSE Linux Enterprise Server 11.x/12.x =====

<source lang="bash">zypper in open-xchange-guard-file-storage</source>
==== S3 Storage Support ====

If you want the S3 storage support, and depending on your Linux distribution, you can install it with the following command:

===== Debian 7.x/8.x =====

<source lang="bash">apt-get install open-xchange-guard-s3-storage</source>
===== RedHat Enterprise Linux 6.x/7.x or CentOS 6.x/7.x =====

<source lang="bash">yum install open-xchange-guard-s3-storage</source>
===== SUSE Linux Enterprise Server 11.x/12.x =====

<source lang="bash">zypper in open-xchange-guard-s3-storage</source>
=== Step 4 - Install open-xchange-rest ===

OX Guard requires access to existing middleware hosts. The endpoint is configured within the <code>guard-core.properties</code> which you can find in <code>/opt/open-xchange/etc</code>. The endpoint configured via <code>com.openexchange.guard.restApiHostname</code> need to have the package <code>open-xchange-rest</code> installed to be able to retrieve and process OX Guard REST requests.

Normally the post installation scripts from the open-xchange-guard package should take over the formerly configured endpoint so that you do not have to do anything.

=== Step 5 - Ensure that the server keys are readable by the sever ===

The <code>oxguardpass</code> file should be owned by the <code>open-xchange</code> user and have the permission 400, meaning read access only by the owner of the file.

<source lang="bash">ls -l /opt/open-xchange/etc/oxguardpass
-r-------- 1 open-xchange root 64 Nov 17 19:14 /opt/open-xchange/etc/oxguardpass</source>
=== Step 6 - Ensure that the Apache balancer directive uses the correct port ===

Since OX Guard is part of the OSGi stack and Grizzly is used to register and serve the OX Guard servlets, the <code>oxguard</code> and <code>oxguardpgp</code> balancer directives in the Apache configuration have to be adjusted in order to set the correct port and possibly removed.

If the Proxy balancer for the backend (oxcluster) is the same as the Guard servers, then you can remove the balancer entries for Guard and just redirect the ProxyPass directive to the oxcluster like so

ProxyPass /appsuite/api/oxguard balancer://oxcluster/oxguard
ProxyPass /pks balancer://oxcluster/pgp

Otherwise, if the Guard servers are different from your backend, find the balancers containing

<source lang="bash">BalancerMember http://guardserver:8080/oxguard timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1
BalancerMember http://guardserver:8080/pgp timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1</source>

The second Balancer (oxguardpgp) for PGP should just be removed. The primary Guard balancer should look like below, removing the sub-directory "/oxuard"

<Proxy balancer://oxguard>
BalancerMember http://guardserver:8009 timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1

The find the lines with the ProxyPass for </appsuite/api/oxguard> and change the balancer to //oxguard/oxguard
Add the PGP balancer if you are exposing the PGP Public key server.

<Proxy /appsuite/api/oxguard>
ProxyPass balancer://oxguard/oxguard
</Proxy>
<Proxy /pks>
ProxyPass balancer://oxguard/pgp
</Proxy>

''' Please note ''': You cannot have more than one BalancerMember with the same URL. So, if changing to the same URL as the OX Backend, you should just remove the Guard entries otherwise there will be some errors reported by Apache, and only the first entry will be used.

=== Step 7 - Adapt configuration ===

This chapter is only valid for '''OX Guard-only node''' where no additional middleware services haven't been desired and installed before! As Guard is now using existing middleware mechanisms to access the databases you have to configure the following properties.

* <code>configdb.properties</code>
* copy an already configured file from a middleware node to <code>/opt/open-xchange/etc</code> on the OX Guard node.
* <code>system.properties</code>
* copy an already configured file from a middleware node to <code>/opt/open-xchange/etc</code> on the OX Guard node.
* <code>server.properties</code>
* set <code>com.openexchange.connector.networkListenerHost</code> to your desired hosts (e. g. <code>*</code>)
* <code>logback.xml</code>
* consolidate your old OX Guard <code>logback.xml</code> with the new one from within <code>/opt/open-xchange/etc</code>
* <code>jolokia.properties</code>
* copy an already configured file from a middleware node to <code>/opt/open-xchange/etc</code> on the OX Guard node.
* <code>mpasswd</code>
* copy your existing <code>oxadminmaster</code> credential storage to <code>/opt/open-xchange/etc</code> on the OX Guard node.
* <code>guard-api.properties</code>
* Adapt the property <code>com.openexchange.guard.endpoint</code>. This can be as simple as replacing the old port 8080 with 8009 but may differ depending on your setup
* Adapt the property <code>com.openexchange.guard.externalReaderUrl</code>. Adjust to the new location of the Guard reader under apache. Defaults to domain/guard/reader/reader.html

After copying those files, please make sure that they are owned by the group <code>open-xchange</code>, otherwise they cannot be read by the middleware service. In addition to the above mentioned properties you may would like to change the default configuration if the underlying middleware instance is only used for OX Guard:

* Disable Hazelcast cluster discovery
* <code>hazelcast.properties: com.openexchange.hazelcast.network.join=empty</code>
* remove all permissions set via configuration
* <code>permissions.properties</code>: set entries to <code>false</code>

=== Step 8 - Restart the groupware ===

Last, and certainly not least, you need to restart the groupware process:

===== Debian 7.x/RedHat Enterprise Linux 6.x/CentOS 6.x/SUSE Linux Enterprise Server 11.x =====

<source lang="bash">service open-xchange restart</source>
===== Debian 8.x/RedHat Enterprise Linux 7.x/CentOS 7.x/SUSE Linux Enterprise Server 12.x =====

<source lang="bash">systemctl restart open-xchange</source>
=== Step 9 - Execute update tasks ===

Before OX Guard should receive the first requests you have to ensure that all database schemas are up to date. This can be done by executing <code>/opt/open-xchange/sbin/runupdate</code>.

Congratulations! You should now have a running OX Guard 2.4.0!

=== Common Problems ===

==== When trying to decode a message I get a 404 ====

This happens probably because the AppSuite ProxyPass Location directives are overwriting the OX Guard ones. To solve this, you will have to move the OX Guard ProxyPass Location directive right before the AppSuite ones.

Change the ordering of the locations from this:

<source lang="bash"><Location /ajax>
ProxyPass balancer://oxcluster/ajax
</Location>
<Location /appsuite/api>
ProxyPass balancer://oxcluster/ajax
</Location>
<Location /appsuite/api/oxguard>
ProxyPass balancer://oxguard
</Location></source>
to this:

<source lang="bash"><Location /appsuite/api/oxguard>
ProxyPass balancer://oxguard
</Location>
<Location /ajax>
ProxyPass balancer://oxcluster/ajax
</Location>
<Location /appsuite/api>
ProxyPass balancer://oxcluster/ajax
</Location></source>
==== After migration, OX Guard fails to accept any request ====

This may happen if configuration files that were copied during migration do not have the correct permission set. Please have a look at the OX Guard middleware log file to find any <code>ERROR</code> messages. The <code>getmissingservices</code> command-line tool may also help to identify services that have not been started and why they failed to start.

==== After migration, Guest reader doesn't work and report too many redirects ====

The location of the Guest reader has been changed, and is now being handled by apache rather than the Jetty server previously used by Guard.

To maintain compatibility with the Guest emails previously sent, Guard tries to redirect the old URL to the new...which is configured as the externalReaderPath in the guard-core.properties file. Be sure to update this setting to the new location as mentioned above.

AppSuite:OX Guard Upgrade OSGI

2016-04-01T18:13:19Z

Greg.hill: /* Step 6 - Ensure that the Apache balancer directive uses the correct port */

= Upgrading OX Guard from 2.2.x to 2.4.0 =

== Introduction ==

With '''OX Guard 2.4.0''' the first step was made and the product was moved into the OSGi stack. Although OX Guard now has a tighter integration with the core that does not mean that it lost its micro-service character. OX Guard still relies on the support API to accomplish its tasks; tasks like capability check, HTML sanitising and mail address resolving. The database calls however were completely eliminated (along with their support API) and now the core's OSGi services are used for that purpose. The same applies to the configuration.

In the next few sections it is described what was changed and the necessary steps to upgrade from 2.2.x to 2.4.0. For a fresh installation refer to the main [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard OX Guard] article.

== Changes ==

This section covers the changes introduced with OX Guard 2.4.0.

=== Configuration Structure ===

Alongside with the OSGi-fication of the product, a bit of clean up took place, regarding the configuration files and their structure.

The most obvious change was to get rid of the separate <code>/opt/open-xchange/guard</code> directory that the entire configuration was residing in. The contents of this directory are now spread accross the appropriate folders in <code>/opt/open-xchange</code>.

==== Templates ====

The templates (originally located under <code>/opt/open-xchange/guard/templates</code>) were moved to the <code>templates</code> directory of the open-xchange installation, i.e. to <code>/opt/open-xchange/templates/guard</code>.

==== Translations ====

The translations (originally located under <code>/opt/open-xchange/guard/l10n</code>) were moved to the <code>i18n</code> directory of the open-xchange installation, i.e. to <code>/opt/open-xchange/i18n</code>. The translations formerly had a prefix <code>main-*_*.po</code> (i.e. <code>main-de_DE.po</code>) should now start with <code>guard-</code> (i.e. <code>guard-de_DE.po</code>) to be able to differentiate between middleware translations and those provided by OX Guard. Even the <code>languages.xml</code> and those starting with <code>templates-*</code> should be located within the above mentioned <code>i18n</code> directory.

==== Properties ====

===== guard.properties =====

Prior to 2.4.0, there were two <code>guard.properties</code> files, one for the core groupware which contained properties that were used to enable the OX Guard capability to various modules as well as some extra functionality, and one for OX Guard itself, containing all properties for that product. Since the <code>/opt/open-xchange/guard</code> directory was deemed obsolete and subject to be removed and to avoid the name clashing of the two property files, they had to be renamed. A merge was not option, simply because they were provided and used by different packages. Therefore, the properties file <code>guard.properties</code> (under <code>/opt/open-xchange/etc/</code>) which accomodated the properties for the AppSuite Guard bundle is now renamed to <code>guard-api.properties</code>.

The OX Guard <code>guard.properties</code> file (under <code>/opt/open-xchange/guard/etc</code>) which housed all the OX Guard properties, is now renamed and moved under <code>/opt/open-xchange/guard/etc/guard-core.properties</code>.

===== private_dns_key and public_dns_key =====

Those two property files were not needed anymore, thus they were marked as obsolete and removed with OX Guard 2.4.0.

=== Farewell Jetty, welcome Grizzly ===

With the big step OX Guard took and moved into the OSGi stack, Jetty was rendered obsolete and had to be removed as well. OX Guard now uses [https://grizzly.java.net/ Grizzly] to register its servlets.

=== Apache ===

The first change in the Apache configuration is the port number of the balancer directive regarding OX Guard. Since Jetty was removed and Grizzly is in charge now, the port was adjusted to reflect that change.

The second change is the order of the ProxyPass locations. The OX Guard one, had to be moved forward because it was getting masked and overwritten by the AppSuite ones.

=== Guest Reader moved to a separate package ===

In order to allow more flexibility on distributed deployments, the "Guest Reader" component has moved to a separate package that is being installed on the frontend server. The UI is then provided by Apache rather than Jetty.

Because of this, the location of the Guest reader URL will change. By default, the reader package will be installed under /var/www/guard/reader

So, in most setups, the reader URL would change from

domain/appsuite/api/oxguard/reader/reader.html?....

to

domain/guard/reader/reader.html?....

To handle this change, the easiest thing to do is change the externalReaderPath configuration in the new guard-core.proprties file from the old location to the new

com.openexchange.guard.externalReaderPath=domain/guard/reader/reader.html

Assuming that there are already several Guest emails out there with the old Jetty URL, Guard OSGI will automatically redirect all requests from the old location to the new

=== Command Line Tool ===

The command line tool also got a "lifting" and was brought to the standards of the rest of the command line tools of the OX family. The CLT now includes optional JMX authentication. Furthermore, the functionality of initialising the OX Guard installation was removed from the command line tool. It is now being done automatically upon server start up. The rest of the functionality is still there, though.

<pre>usage: guard [-i [-d /custom/path]] [-t john.doe@example.com] [-u
joan.doe@ox.io] [-e john.doe@example.com] [-n
joan.doe@example.com] [-j jmxUser] [-w jmxPassword] [-x
jmx.host] [-o <JMX_PORT>] [-p <RMI_PORT>] [--responsetimeout
<TIMEOUT>]
-d,--directory <arg> Full path of the 'oxguardpass' file
(defaults to current directory). This flag
should be used in conjunction with the
'--init' switch.
e.g. guard --init --directory
/opt/open-xchange/etc
-e,--reset <arg> Resets the specified e-mail address and
sends a new password to the user
e.g. guard --reset john@somewhere.com
-h,--help Prints a help text
-i,--init Initialise guard.
-j,--jmx-user <arg> JMX user
-n,--remove-pin <arg> Removes the PIN for the specified user
e.g. guard --remove-pin john@somewhere.com
-o,--jmx-port <arg> JMX port (default: '9999')
-p,--port <arg> The optional RMI port (default:1099)
--responsetimeout <arg> The optional response timeout in seconds
when reading data from server (default: 0s;
infinite)
-s,--server <arg> The optional RMI server (default: localhost)
-t,--test <arg> Test the specified e-mail address against
the MailResolver
e.g. guard --test john@somewhere.com
-u,--upgrade <arg> Upgrades the specified guest account to an
OX account
e.g. guard --upgrade john@somewhere.com
-w,--jmx-password <arg> JMX password
-x,--jmx-host <arg> JMX host (default: 'localhost')

Command line tool for OX Guard</pre>
=== Logging ===

The <code>/opt/open-xchange/guard/etc/logback.xml</code> file for OX Guard was completely removed. Now logging is being configured globally in <code>/opt/open-xchange/etc/logback.xml</code>. All OX Guard events that were previously logged in <code>/var/log/open-xchange/guard/guard.log</code> are now being logged in the log file as the groupware, namely in <code>/var/log/open-xchange/open-xchange.log.0</code>.

The SMTP relevant section is no longer present, but it can be configured separately by adding it again to the previous mentioned <code>logback.xml</code> file.

<source lang="xml">
<appender name="SMTP" class="ch.qos.logback.classic.net.SMTPAppender">
<smtpHost>smtphost</smtpHost>
<to>user@admin</to>
<from>notify@admin</from>
<subject>Guard - %marker - %msg%n </subject>
<layout class="ch.qos.logback.classic.html.HTMLLayout">
<pattern>%date%level%logger{24}%msg</pattern>
</layout>

<evaluator class="ch.qos.logback.classic.boolex.JaninoEventEvaluator">
<expression>
marker != null && (marker.contains("NOTIFY_MAJOR") || marker.contains("NOTIFY_MINOR"))
</expression>
</evaluator>
</appender></source>
The following tag has to be added to the <code>root</code> level in order for this to work.

<source lang="xml"><appender-ref ref="SMTP" /></source>
For example:

<source lang="xml"><root level="INFO">
<appender-ref ref="ASYNC"/>
<appender-ref ref="SMTP" />
</root></source>

== Upgrading from 2.2.x to 2.4.0 ==

There are a few things to consider when upgrading from a version 2.2.x to 2.4.0. In this section we will cover that upgrade path.

The first thing is that the file storage implementations are now being kept into two separate packages, i.e. <code>open-xchange-guard-file-storage</code> and <code>open-xchange-guard-s3-storage</code> for the file storage and S3 storage support respectively. This means that one of the packages has to be manually installed after the upgrade.

The second thing is that the <code>open-xchange-guard</code> system service is now gone. Since, OX Guard is intergraded into the OSGi stack, it will start automatically with the backend, i.e. when the <code>open-xchange</code> system service starts.

With those two things in mind, OX Guard can be upgraded as described [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard#Update_OX_Guard here]. Again, after the upgrade is complete there is no need to restart the <code>open-xchange-guard</code> system service; neither the <code>open-xchange</code> system service should be restarted just yet. There are a few things to do before having a fully functional OX Guard backend.

The Guest Reader component has moved to the <code>open-xchange-guard-reader</code> package, which needs to be installed on the frontend server next to App Suite UI.

=== Step 1 - Enhance repository sources ===

If you currently do not have an Open-Xchange middleware installed you have to adapt your Open-Xchange repository file to be able to solve required dependencies to the middleware packages. Add the following to the file that already should contain an entry for the OX Guard repository.

===== Debian 7.x =====

<source lang="bash">deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
===== Debian 8.x =====

<source lang="bash">deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
===== RedHat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
===== Redhat Enterprise Linux 7 or CentOS 7 =====

<source lang="bash">[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</source>
===== SUSE Linux Enterprise Server 11.x =====

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLES11 ox-backend</source>
===== SUSE Linux Enterprise Server 12.x =====

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>
After adding new repositories retrieve new lists of packages by executing your desired package managers update call.

=== Step 2 - Update OX Guard ===

Upgrade the existing installation by executing your desired package mangers upgrade call, for instance <code>apt-get dist-upgrade</code>, <code>yum upgrade</code> and so on.

If you are running an '''OX Guard-only node''' (because of infelicitous set dependencies) you have to install an implementation of the package <code>open-xchange-authentication</code> and <code>open-xchange-spamhandler</code> which will never be used but checked for. We suggest to install <code>open-xchange-authentication-database</code> and <code>open-xchange-spamhandler-default</code>. Installing those packages as well as chosing a <code>open-xchange-guard-storage</code> implementation will install all required middleware dependencies.

After the update <code>/etc/init.d/open-xchange-guard</code> shouldn't be available any more but OX Guard will start when starting the <code>open-xchange</code> system service.

=== Step 3 - Choose and install your storage ===

According to your previous installation, you will have to manually install the relevant <code>open-xchange-guard-storage</code> package. Of course, you can switch to the one or the other storage if you wish, but be aware that '''no data''' will be migrated. You will have to do this manually.

==== File Storage Support ====

If you want the file storage support, and depending on your Linux distribution, you can install it with the following command:

===== Debian 7.x/8.x =====

<source lang="bash">apt-get install open-xchange-guard-file-storage</source>
===== RedHat Enterprise Linux 6.x/7.x or CentOS 6.x/7.x =====

<source lang="bash">yum install open-xchange-guard-file-storage</source>
===== SUSE Linux Enterprise Server 11.x/12.x =====

<source lang="bash">zypper in open-xchange-guard-file-storage</source>
==== S3 Storage Support ====

If you want the S3 storage support, and depending on your Linux distribution, you can install it with the following command:

===== Debian 7.x/8.x =====

<source lang="bash">apt-get install open-xchange-guard-s3-storage</source>
===== RedHat Enterprise Linux 6.x/7.x or CentOS 6.x/7.x =====

<source lang="bash">yum install open-xchange-guard-s3-storage</source>
===== SUSE Linux Enterprise Server 11.x/12.x =====

<source lang="bash">zypper in open-xchange-guard-s3-storage</source>
=== Step 4 - Install open-xchange-rest ===

OX Guard requires access to existing middleware hosts. The endpoint is configured within the <code>guard-core.properties</code> which you can find in <code>/opt/open-xchange/etc</code>. The endpoint configured via <code>com.openexchange.guard.restApiHostname</code> need to have the package <code>open-xchange-rest</code> installed to be able to retrieve and process OX Guard REST requests.

Normally the post installation scripts from the open-xchange-guard package should take over the formerly configured endpoint so that you do not have to do anything.

=== Step 5 - Ensure that the server keys are readable by the sever ===

The <code>oxguardpass</code> file should be owned by the <code>open-xchange</code> user and have the permission 400, meaning read access only by the owner of the file.

<source lang="bash">ls -l /opt/open-xchange/etc/oxguardpass
-r-------- 1 open-xchange root 64 Nov 17 19:14 /opt/open-xchange/etc/oxguardpass</source>
=== Step 6 - Ensure that the Apache balancer directive uses the correct port ===

Since OX Guard is part of the OSGi stack and Grizzly is used to register and serve the OX Guard servlets, the <code>oxguard</code> and <code>oxguardpgp</code> balancer directives in the Apache configuration have to be adjusted in order to set the correct port and possibly removed.

If the Proxy balancer for the backend (oxcluster) is the same as the Guard servers, then you can remove the balancer entries for Guard and just redirect the ProxyPass directive to the oxcluster like so

ProxyPass /appsuite/api/oxguard balancer://oxcluster/oxguard
ProxyPass /pks balancer://oxcluster/pgp

Otherwise, if the Guard servers are different from your backend, find the lines like

<source lang="bash">BalancerMember http://guardserver:8080/oxguard timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1
BalancerMember http://guardserver:8080/pgp timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1</source>

The second Balancer (oxguardpgp) for PGP should just be removed. The primary Guard balancer should look like below, removing the sub-directory "/oxuard"

<Proxy balancer://oxguard>
BalancerMember http://guardserver:8009 timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1

The find the lines with the ProxyPass for </appsuite/api/oxguard> and change the balancer to //oxguard/oxguard
Add the PGP balancer if you are exposing the PGP Public key server.

<Proxy /appsuite/api/oxguard>
ProxyPass balancer://oxguard/oxguard
</Proxy>
<Proxy /pks>
ProxyPass balancer://oxguard/pgp
</Proxy>

''' Please note ''':

=== Step 7 - Adapt configuration ===

This chapter is only valid for '''OX Guard-only node''' where no additional middleware services haven't been desired and installed before! As Guard is now using existing middleware mechanisms to access the databases you have to configure the following properties.

* <code>configdb.properties</code>
* copy an already configured file from a middleware node to <code>/opt/open-xchange/etc</code> on the OX Guard node.
* <code>system.properties</code>
* copy an already configured file from a middleware node to <code>/opt/open-xchange/etc</code> on the OX Guard node.
* <code>server.properties</code>
* set <code>com.openexchange.connector.networkListenerHost</code> to your desired hosts (e. g. <code>*</code>)
* <code>logback.xml</code>
* consolidate your old OX Guard <code>logback.xml</code> with the new one from within <code>/opt/open-xchange/etc</code>
* <code>jolokia.properties</code>
* copy an already configured file from a middleware node to <code>/opt/open-xchange/etc</code> on the OX Guard node.
* <code>mpasswd</code>
* copy your existing <code>oxadminmaster</code> credential storage to <code>/opt/open-xchange/etc</code> on the OX Guard node.
* <code>guard-api.properties</code>
* Adapt the property <code>com.openexchange.guard.endpoint</code>. This can be as simple as replacing the old port 8080 with 8009 but may differ depending on your setup
* Adapt the property <code>com.openexchange.guard.externalReaderUrl</code>. Adjust to the new location of the Guard reader under apache. Defaults to domain/guard/reader/reader.html

After copying those files, please make sure that they are owned by the group <code>open-xchange</code>, otherwise they cannot be read by the middleware service. In addition to the above mentioned properties you may would like to change the default configuration if the underlying middleware instance is only used for OX Guard:

* Disable Hazelcast cluster discovery
* <code>hazelcast.properties: com.openexchange.hazelcast.network.join=empty</code>
* remove all permissions set via configuration
* <code>permissions.properties</code>: set entries to <code>false</code>

=== Step 8 - Restart the groupware ===

Last, and certainly not least, you need to restart the groupware process:

===== Debian 7.x/RedHat Enterprise Linux 6.x/CentOS 6.x/SUSE Linux Enterprise Server 11.x =====

<source lang="bash">service open-xchange restart</source>
===== Debian 8.x/RedHat Enterprise Linux 7.x/CentOS 7.x/SUSE Linux Enterprise Server 12.x =====

<source lang="bash">systemctl restart open-xchange</source>
=== Step 9 - Execute update tasks ===

Before OX Guard should receive the first requests you have to ensure that all database schemas are up to date. This can be done by executing <code>/opt/open-xchange/sbin/runupdate</code>.

Congratulations! You should now have a running OX Guard 2.4.0!

=== Common Problems ===

==== When trying to decode a message I get a 404 ====

This happens probably because the AppSuite ProxyPass Location directives are overwriting the OX Guard ones. To solve this, you will have to move the OX Guard ProxyPass Location directive right before the AppSuite ones.

Change the ordering of the locations from this:

<source lang="bash"><Location /ajax>
ProxyPass balancer://oxcluster/ajax
</Location>
<Location /appsuite/api>
ProxyPass balancer://oxcluster/ajax
</Location>
<Location /appsuite/api/oxguard>
ProxyPass balancer://oxguard
</Location></source>
to this:

<source lang="bash"><Location /appsuite/api/oxguard>
ProxyPass balancer://oxguard
</Location>
<Location /ajax>
ProxyPass balancer://oxcluster/ajax
</Location>
<Location /appsuite/api>
ProxyPass balancer://oxcluster/ajax
</Location></source>
==== After migration, OX Guard fails to accept any request ====

This may happen if configuration files that were copied during migration do not have the correct permission set. Please have a look at the OX Guard middleware log file to find any <code>ERROR</code> messages. The <code>getmissingservices</code> command-line tool may also help to identify services that have not been started and why they failed to start.

==== After migration, Guest reader doesn't work and report too many redirects ====

The location of the Guest reader has been changed, and is now being handled by apache rather than the Jetty server previously used by Guard.

To maintain compatibility with the Guest emails previously sent, Guard tries to redirect the old URL to the new...which is configured as the externalReaderPath in the guard-core.properties file. Be sure to update this setting to the new location as mentioned above.

AppSuite:OX Guard

2016-04-01T18:00:50Z

Greg.hill: /* Support API */

= OX Guard (Version 2.4+ )=

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

=== Important Notes ===

==== Customisation ====

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 Customisation] 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.

Be sure to test the mail resolver using:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-rest</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code>

The components required for the OX frontend are: <code>open-xchange-guard-ui</code> <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files)

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 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== RedHat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== SUSE Linux Enterprise Server 11 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLES11 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in 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</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefore we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</source>
=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</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 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>
== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Redhat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== SUSE Linux Enterprise Server 11 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLES11 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLES11 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== 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.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><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</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> 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 BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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 starting the initialization. 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</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.

'''Guard Mail''' and '''Guard Drive''' 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.

Each of those two 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 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>
==== Guard Drive: ====

<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 bakend.

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>
==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><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.
ProxyPass /preliminary balancer://oxcluster/preliminary
</Location></source>
Make sure that the balancer is properly configured in the <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>
==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== 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.properties file using the following settings:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportapiusername=
com.openexchange.guard.supportapipassword=</source>
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. But if you want to expose the Guard Support API using Apache a very basic Apache configuration could look like this:

'''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 ===

<code>POST /guardsupport/?action=reset_password</code>

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. The reset password function is currently not available for guest users. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard

2016-04-01T17:58:40Z

Greg.hill: /* External */

= OX Guard (Version 2.4+ )=

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

=== Important Notes ===

==== Customisation ====

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 Customisation] 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.

Be sure to test the mail resolver using:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-rest</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code>

The components required for the OX frontend are: <code>open-xchange-guard-ui</code> <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files)

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 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== RedHat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== SUSE Linux Enterprise Server 11 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLES11 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in 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</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefore we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</source>
=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</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 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>
== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Redhat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== SUSE Linux Enterprise Server 11 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLES11 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLES11 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== 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.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><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</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> 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 BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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 starting the initialization. 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</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.

'''Guard Mail''' and '''Guard Drive''' 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.

Each of those two 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 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>
==== Guard Drive: ====

<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 bakend.

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>
==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><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.
ProxyPass /preliminary balancer://oxcluster/preliminary
</Location></source>
Make sure that the balancer is properly configured in the <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>
==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== 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.properties file using the following settings:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportapiusername=
com.openexchange.guard.supportapipassword=</source>
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. But if you want to expose the Guard Support API using Apache a very basic Apache configuration could look like this:

'''Warning''': Exposing the support API to the internet could be huge security risk. Only add to Apache if you know what you are doing:

<source lang="bash"><Location /appsuite/api/guardsupport>
ProxyPass http://localhost:8009/guardsupport
#...
</Location></source>
It might also be preferable to add a new balancer directive for <code>guardsupport</code>

<source lang="bash"><Location /appsuite/api/guardsupport>
ProxyPass balancer://oxguardsupport
</Location>
<Proxy balancer://oxguardsupport>
#...
BalancerMember http://localhost:8009/guardsupport #...
#...
</Proxy></source>
=== Reset password ===

<code>POST /guardsupport/?action=reset_password</code>

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. The reset password function is currently not available for guest users. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

AppSuite:OX Guard

2016-04-01T17:57:39Z

Greg.hill: /* Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 */

= OX Guard (Version 2.4+ )=

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0|Installation and information of OX Guard 2.0 - 2.2]]

If upgrading from 2.0 or 2.2, please see the following article
* [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]]

== 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. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard 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. OX App Suite v7.8.1 or later is required to operate this extension both in a single or multi server environments.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 7)
* An Open-Xchange App Suite installation v7.8.1 or later
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

=== Important Notes ===

==== Customisation ====

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 Customisation] 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.

Be sure to test the mail resolver using:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-rest</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 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: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code>

The components required for the OX frontend are: <code>open-xchange-guard-ui</code> <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files)

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 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://software.open-xchange.com/products/guard/stable/guard/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
The packages <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.

=== RedHat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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</source>
and then run for a single node installation:

<source lang="bash">$ 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</source>
or the following for a distributed installation:

<source lang="bash">$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

=== SUSE Linux Enterprise Server 11 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLES11 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLES11 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in 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</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefore we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</source>
=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

<source lang="bash">$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend</source>
and then run for a single node installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static</source>
or the following for a distributed installation:

<source lang="bash">$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static </source>
The packages <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.

Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:

<source lang="bash">$ update-alternatives --config java</source>
Now select the Java 1.7 JRE, example:

<source lang="bash">There are 2 alternatives which provide 'java'.

Selection Alternative
-----------------------------------------------
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java

Press enter to keep the default[*], or type selection number: 2
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.</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 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:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>
== Update OX Guard ==

This section contains information about updating a 2.4.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. You can find more information in the '''Update OX Guard Versions <= 2.2.x''' and '''Update OX Guard Versions <= 2.0.x''' sections below.

=== Debian Linux 7.0 (Wheezy) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianWheezy /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Debian Linux 8.0 (Jessie) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

<source lang="bash">deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianJessie /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianJessie /</source>
Then run:

<source lang="bash">$ 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:

<source lang="bash">$ apt-get dist-upgrade -s</source>
=== Redhat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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/RHEL6/
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/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>
and then run:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

<source lang="bash">[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:

<source lang="bash">$ yum update
$ yum upgrade</source>
=== SUSE Linux Enterprise Server 11 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLES11 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLES11 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

<source lang="bash">$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>
and then run:

<source lang="bash">$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>
You might need to run:

<source lang="bash">$ zypper ref</source>
to update the repository metadata before running <code>zypper</code> up.

=== 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.

=== Update OX Guard Versions <= 2.2.x ===

If you are upgrading from a 2.2 version to 2.4, please read the [[Appsuite:OX_Guard_Upgrade_OSGI|Upgrading from 2.0 or 2.2 to 2.4]] article.

== 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 <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
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 <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== 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:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>
===== Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11 =====

<source lang="bash">$ vim /etc/apache2/conf.d/proxy_http.conf</source>
<source lang="bash"><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</source>

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code><Proxy /appsuite/api></code> 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 BalacnerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

==== Open-Xchange ====

Edit the <code>guard-api.properties</code> configuration file for the OX backend which contain some general Guard settings. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># 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</source>
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 <code>/guardadmin</code>. 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:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># 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</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== 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:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

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 <code>/opt/open-xchange/etc/oxguardpass</code>. 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> 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 starting the initialization. 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)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
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 two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</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.

'''Guard Mail''' and '''Guard Drive''' 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.

Each of those two 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 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>
==== Guard Drive: ====

<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 bakend.

=== 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 <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver 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. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.open-xchange.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>
You will also need to make additional entries in the apache <code>proxy_http.conf</code> file.

<source lang="bash"><Proxy balancer://oxguardpgp>
Order deny,allow
Allow from all, add
BalancerMember http://guardserver:8009/pgp timeout=1800 smax=0 ttl=60 retry=60 loadfactor=50 route=OX3
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>
<Proxy /pks>
ProxyPass balancer://oxguardpgp
</Proxy></source>
'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

=== 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 <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. 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:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>
==== 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 <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<source lang="bash"><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.
ProxyPass /preliminary balancer://oxcluster/preliminary
</Location></source>
Make sure that the balancer is properly configured in the <code>mod_proxy</code> 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 <code>/preliminary</code> 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 <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) 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 <code>/</code> 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):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>
==== 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:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
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):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
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 <code>/preliminary</code> 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 <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

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 [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== 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.properties file using the following settings:

<source lang="bash"># Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportapiusername=
com.openexchange.guard.supportapipassword=</source>
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. But if you want to expose the Guard Support API using Apache a very basic Apache configuration could look like this:

'''Warning''': Exposing the support API to the internet could be huge security risk. Only add to Apache if you know what you are doing:

<source lang="bash"><Location /appsuite/api/guardsupport>
ProxyPass http://localhost:8009/guardsupport
#...
</Location></source>
It might also be preferable to add a new balancer directive for <code>guardsupport</code>

<source lang="bash"><Location /appsuite/api/guardsupport>
ProxyPass balancer://oxguardsupport
</Location>
<Proxy balancer://oxguardsupport>
#...
BalancerMember http://localhost:8009/guardsupport #...
#...
</Proxy></source>
=== Reset password ===

<code>POST /guardsupport/?action=reset_password</code>

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. The reset password function is currently not available for guest users. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

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:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

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:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization 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 [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.