AppSuite:OX Guard Configuration 2 10 - Revision history

Greg.hill: /* S3-Storage */

2023-02-13T13:27:54Z

S3-Storage

← Older revision		Revision as of 13:27, 13 February 2023
Line 100:		Line 100:

	==== S3-Storage ====		==== 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 =		<source lang="bash">com.openexchange.guard.storage.s3.endpoint =
	com.openexchange.guard.storage.s3.bucketName =		com.openexchange.guard.storage.s3.bucketName =
Line 106:		Line 120:
	com.openexchange.guard.storage.s3.accessKey =		com.openexchange.guard.storage.s3.accessKey =
	com.openexchange.guard.storage.s3.secretKey =</source>		com.openexchange.guard.storage.s3.secretKey =</source>
	~~S3 configuration options if the package <code>open-xchange-guard-s3-storage</code> is selected.~~

	=== Crypto ===		=== Crypto ===

Greg.hill at 14:37, 25 January 2023

2023-01-25T14:37:17Z

← Older revision		Revision as of 14:37, 25 January 2023
Line 6:		Line 6:

	=== Main Properties ===		=== 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>		<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.		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>		<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		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>		<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		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 ===		=== Optional Properties ===
Line 30:		Line 35:

	<source lang="bash">com.openexchange.capability.guard-nodeleteprivate = true</source>		<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.		(Guard 2.0) Disable the ability of the user to delete their PGP 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>) ==		== Configuration File (<code>guard-core.properties</code>) ==
Line 133:		Line 132:
	<pre>com.openexchange.guard.useStartTLS = true</pre>		<pre>com.openexchange.guard.useStartTLS = true</pre>
	Use TLS when delivering to the SMTP server when available		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) ===		=== Autocrypt (as of 2.10.2) ===
Line 157:		Line 163:
	Defines how many times a person can attempt to unlock an encrypted item before being locked out. Defaults to 5 times.		Defines how many times a person can attempt to unlock an encrypted item before being locked out. Defaults to 5 times.

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

	<source lang="bash">com.openexchange.guard.rsacache = true</source>		<source lang="bash">com.openexchange.guard.rsacache = true</source>

Greg.hill: /* Optional Properties */

2019-09-27T18:25:17Z

Optional Properties

← Older revision		Revision as of 18:25, 27 September 2019
Line 19:		Line 19:

	<source lang="bash">com.openexchange.guard.templateID = 0</source>		<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.		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>		<source lang="bash">com.openexchange.guard.endpoint =</source>

Greg.hill: /* PGP */

2019-03-21T17:01:52Z

PGP

← Older revision		Revision as of 17:01, 21 March 2019
Line 133:		Line 133:
	<pre>com.openexchange.guard.useStartTLS = true</pre>		<pre>com.openexchange.guard.useStartTLS = true</pre>
	Use TLS when delivering to the SMTP server when available		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 ===		=== Email ===

Greg.hill: /* Guest Accounts */

2019-03-21T16:54:37Z

Guest Accounts

← Older revision		Revision as of 16:54, 21 March 2019
Line 184:		Line 184:
	<source lang="bash">com.openexchange.guard.shardsize=1000</source>		<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		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 ===		=== Recovery ===

Greg.hill: /* PGP */

2019-03-21T16:49:45Z

PGP

← Older revision		Revision as of 16:49, 21 March 2019
Line 131:		Line 131:
	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.		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>		<pre>com.openexchange.guard.useStartTLS = true</pre>
	Use TLS when delivering to the SMTP server when available		Use TLS when delivering to the SMTP server when available

Greg.hill: /* Initial 2.10 configuration */

2018-03-13T13:47:33Z

Initial 2.10 configuration

New page

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