Guard deprecated

Configuring and debugging OX Guard

This document describes how to perform common debugging and configuration tasks related to OX Guard using the Toolkit Container.


Note:

See https://documentation.open-xchange.com/components/guard/8/articles/ for a documentation of general OX Guard topics.

Prerequisites

Key and certificate handling

The guard command-line tool offers various subcommands for importing and exporting key and certificate-related data.

Import

Importing an S/MIME Certificate Authority Certificate

The cacert subcommand is used to import a Certificate Authority (CA) certificate into the system's trusted store. This allows the system to trust digital signatures and encrypted messages from entities certified by that CA.

The certificate will not be globally trusted by all users. Instead, the group ID, passed using the --groupid flag, defines which users will trust the certificate. Only users in the specified group, as configured with the server-side com.openexchange.smime.caGroupId setting, will be able to trust the certificate.

The certificate file path is given as the first positional argument and must point to a PEM-encoded text file.

mwctl guard import cacert -g <GROUP-ID> <FILE>

See https://documentation.open-xchange.com/components/guard/8/articles/Smime.html#certificate-authorities for more information.

Importing an S/MIME user certificate

The cert subcommand is used to import an S/MIME certificate and assign it to a specific user. The certificate file path is given as the first positional argument and must point to a PKCS#12-encoded certificate file.

mwctl guard import cert -c <CONTEXT-ID> -i <USER-ID> <FILE>

Note:

During the import, the certificate will be assigned a new password, which you will be prompted to enter.

Importing a PGP public key

The pgppublic subcommand imports a local file containing a public PGP key and publishes it via OX Guard's HKP (HTTP Keyserver Protocol) endpoint, making the key publicly available for retrieval by others.

The PGP file path is given as the first positional argument and must point to a PEM-encoded PGP Public Key file.

mwctl guard import pgppublic <FILE>

Note:

Unlike typical user-bound PGP keys, this key usually represents a system, group, or company identity. It is published alongside individual user keys to enable verification and secure communication at an organizational or system level.

Export

Exporting a report about expiring S/MIME certificates

The expiring subcommand creates a brief report of S/MIME certificates that will expire within the specified time frame.

By default it will list the certificates which will expire in the next 31 days.

mwctl guard export expiring

Tip:

You can use the -d (--days) flag to specify a custom range in days.

Delete OX Guard entities

Deleting all keys of a user.

You can use the keys subcommand to delete ALL keys of a specific type (PGP or SMIME) belonging to a certain user.

mwctl guard delete keys --type <PGP|SMIME> -c <CONTEXT-ID> -i <USER-ID>

Note:

This will remove ALL keys or certificates of the user! If the keys or certificates are removed, the user will no longer be able to encrypt or decrypt messages that rely on them. However, the user can start over by creating fresh keys and certificates.

Deleting a user's secondary email address

The secondaryEmail subcommand deletes the additional email address stored for a user, which can be used for password resets. If the additional email address is deleted, the user's primary email address will be used for future password resets.

mwctl guard delete secondaryEmail -c <CONTEXT-ID> -i <USER-ID>

Deleting a Guest User's PIN

The PIN subcommand deletes a guest user's PIN token, which is used as a second-factor authentication method during the initial account setup when the guest user reads their email for the first time. If the guest loses the PIN and the sender is also unable to retrieve it from the sent message, the PIN can be removed. After this, the guest is able to set up their account without requiring a PIN anymore.

mwctl guard delete pin <EMAIL>

Password reset

The reset subcommand is used to reset as user's Guard password. The user can be either an internal Guard user or a Guard guest.

The command requires the user's email address (either a regular OX Guard user or a guest user) and the type of password (--type) that should be reset.

mwctl guard reset --type <PGP|SMIME> <EMAIL>

If the target user is a Guard guest, the --invited-by flag must be provided to specify the email address of the user who re-invites them. In this case, the password is not directly reset. Instead, a new invitation link is generated, allowing the guest to create a new PGP key and set a new password themselves. The --invited-by information is also used for formatting and templating purposes during this process.

Debug

Clearing OX Guard caches

The clearcaches subcommand can be used to clear and invalidate several OX Guard caches.

mwctl guard debug clearcaches

Detecting and repairing broken database entries

The repairdb subcommand detects and repairs inconsistencies in the Guard databases tables.

This tool triggers a consistency check of the database to identify and report inconsistencies.
By default, the tool runs in detection mode and performs a read-only analysis without making any changes. 

mwctl guard repairdb

To apply automatic fixes to identified issues, use the "-write" flag to enable write mode.

mwctl guard repairdb --write

Testing the "Mail Resolver"

The resolve subcommand tests whether the given email address resolves to a local OX App Suite user.

You can specify the email address to resolve as the first positional argument.

mwctl guard debug resolve <EMAIL>