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.
See https://documentation.open-xchange.com/components/guard/8/articles/ for a documentation of general OX Guard topics.
Prerequisites
- An active shell to a running Toolkit Container within the cluster. See Starting.
- Access to the OX Middleware / Guard Rest API (see
com.openexchange.guard.restApiHostname
,com.openexchange.guard.restApiUsername
andcom.openexchange.guard.restApiPassword
- https://documentation.open-xchange.com/components/guard/8.25/properties/basics.html )
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>
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>
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
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>
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>
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>