AppSuite:Updating To Guard PGP

Guard Update

Starting with Guard 2.0, the proprietary Guard format is discontinued in favor of PGP encryption. The proprietary format is still supported for decoding/reading, but all future encryption will be done with PGP compliant encryption.

The upgrade from 1.2 to 2.0 requires database modification and data population. During the update, Guard 1.2 servers can continue to operate. During the alter tables, no additional Guard members can be added, but users can continue to encrypt and decode items. After the alter table is complete, a data population phase begins. During this phase, lookup tables are created for the existing PGP public keys. Depending on the number of users, this may take a while, but there will be no impact on the functioning Guard 1.2 servers.

The database upgrade is required for Guard 2.0 to function, but Guard 1.2 will function without issue on the updated database.

Guard Upgrade Process

Install Guard 2.0 on the server you would like to do the upgrade. The guard.properties file should reflect all of the database and REST API settings as before. There have been some changes in the guard.properties file (addressed below), but there are no changes required for the update process

Step 1: Test installation

Once the installation is complete, it is often best to test that Guard is configured properly and able to communiate with the OX backend. Use an email address that is a user on the OX system...for this example, we'll use john@doe.com

On command line:

/opt/open-xchange/sbin/guard test john@doe.com

Guard should return a result similar to

 Response received.  Testing JSON
 {"john@doe.com":{"uid":13,"user":{"language":"en_US","displayName":"John Smith"},"cid":10}}
 User id 13
 Context 10
 Language en_US
 Name John Smith
 Success

If you do not get a "Success", then check the logs and guard.properties file for a configuration issue.

Step 2: Upgrade

Once the installation is verified, the upgrade process can begin.

On command line:

/opt/open-xchange/sbin/guard upgradePGP

This will begin the upgrade process. First, the required database alter function are performed. This is the only stage that locks the tables. During this process, no additional Guard users can be created.

Once this is done, then the lookup tables are populated. Progress will be written to the console.

Once complete, the database upgrade is finished.

Step 3: Configuration File

There are some minor changes to the Guard backend's guard.properties file. This file will have to be altered on each of the Guard servers when they are each updated.

PGP lookup

When a user tries to send a PGP email to a recipient, Guard will check configured public key servers for the recipients PGP Public key. You can configure which servers are used in a comma deliminated list.

com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371

External Email URL

The URL for the external guest reader has been changed. The value can now be configured through the configuration cascade so that a custom domain can be used for each context. The guard.properties file contains the default value if the configuration cascade is not present

com.openexchange.guard.externalReaderPath=example.com/appsuite/api/oxguard/reader/reader.html

This value will be used as the default unless over-written by cascade value com.openexchange.guard.externalReaderURL

Finally, each PGP email is also sent with a help file that explains what PGP is, and how to log onto Appsuite to view the email. The domain for appsuite should be configured here

com.openexchange.guard.externalEmailURL=example.com

Step 4: Start

Start Guard 2.0 using (Debian)

/etc/init.d/open-xchange-guard start