mguard-atv-merge

mguard-config-tool

Overview and Motivation

The mGuard security router series is a family of firewall/router devices that is produced by the PHOENIX CONTACT Cyber Security GmbH, a member of the PHOENIX CONTACT group. An mGuard in connection with the mGuard Secure Cloud can be used for remote servicing machines in the field via IPSec-VPN.

Setting up an mGuard in the mGuard Secure Cloud generates a configuration file containing everything that is needed to connect to the cloud. The configuration file can then be loaded into the mGuard to set it up properly. As a configuration file is a snapshot of all settings, loading a configuration file replaces existing settings in the mGuard. Therefore it is not possible to have custom settings along with the configuration file generated by the cloud. A tool that is able to merge two configurations into one would be handy. This is where the mGuard-Config-Tool comes into play.

The mGuard-Config-Tool aims to ease handling mGuard configuration files. It's main features are:

• Support for ATV files and ECS containers (unencrypted + encrypted)
• Tasks
  • User Management: Add users and set/verify passwords
  • Conditioning: Condition a configuration and convert formats (ATV <=> ECS)
  • Merging: Merge two configurations into one
• On Windows: Service for merging configurations and creating update packages

Releases

mGuard-Config-Tool is written in GO which makes it highly portable.

Downloads are provided for the following combinations of popular target operating systems and platforms:

• Linux
  • Intel x86 Platform (386)
  • Intel x64 Platform (amd64)
  • ARM 32-bit Platform (arm)
  • ARM 64-bit Platform (arm64)
• Windows
  • Intel x86 Platform (386)
  • Intel x64 Platform (amd64)

If any other target operating system and/or platform is needed and the combination is supported by GO, please open an issue and we'll add support for it.

Prerequisites

OpenSSL

Writing encrypted ECS containers requires the openssl application to be installed. The directory containing the openssl executable should be in the search path.

Linux

On linux systems the openssl can be installed using the system's package manager. Usually it is already in the search path.

Windows

On Windows systems the openssl can be downloaded here. The search path must be adjusted manually on your system to point to the appropriate directory (most likely: C:\Program Files\OpenSSL-Win64\bin). If you use the service mode only, you can also explicitly specify the path of the openssl executable in the service configuration (see below).

Device Database Access

Writing encrypted ECS containers also requires access to the mGuard device database. To retrieve device certificates you have to register for an account. This can be done using the registration form. Although the mGuard is distributed by Phoenix Contact now, the URL contains the name of the original manufacturer Innominate, so don't suprised. Firthermote the registration form contains some fields, that are deprecated now and should be filled with fake data. So you can securely pass the following fields:

• Reseller: TLK
• Number of Devices: 100
• Date of Purchase: 1.1.2010

The registration process seems to require some manual interaction, so it may take some days. If you don't get an e-mail with the credentials to access the database, please contact the Phoenix Contact representative responsible for your company.

Usage

The mGuard-Config-Tool is a console application that uses subcommands to run different tasks. The application writes log messages to stderr, so it's easy to pipe them into a log file or discard them entirely. The stdout channel is used for emitting content only.

If you intend to write encrypted ECS files, the mGuard-Config-Tool needs access to the mGuard device database to retrieve mGuard specific device certificates. See above on how to get access to the device database. Please put the database credentials into the file mguard-device-database.yaml and place it beside the mguard-config-tool(.exe) executable.

The following snippet shows an example:

credentials:
  user: "user@domain.com"          # username to use when authenticating to the mGuard device database
  password: "my-secret-password"   # password to use when authenticating to the mGuard device database

Subcommand: user

The user subcommand provides access to the user management. All operations run on ECS files only, but support an implicit conversion if an ATV file is specified. ATV files do not contain information about user accounts and passwords.

By default the unencrypted ECS container to work on is expected to be passed via stdin to ease scripting without generating temporary files. The output of these operations is an unencrypted ECS container that is written to stdout. Optionally input and output can be regular files as well by specifying --ecs-in and --ecs-out appropriately.

user - Add user and set/verify user passwords (ECS containers only).

  Usage:
        user [add|password]

  Subcommands:
    add        Add a user.
    password   Set or verify the password of a user.

  Flags:
       --version   Displays the program version string.
    -h --help      Displays help with available flag, subcommand, and positional value parameters.
       --verbose   Include additional messages that might help when problems occur.

The subcommand user add allows to add new users:

add - Add a user.

  Usage:
        add [username] [password]

  Positional Variables:
        username   Login name of the user. (Required)
        password   Password of the user. (Required)

  Flags:
       --version   Displays the program version string.
    -h --help      Displays help with available flag, subcommand, and positional value parameters.
       --ecs-in    The ECS container (unencrypted, instead of stdin).
       --ecs-out   File receiving the updated ECS container (unencrypted, instead of stdout).
       --verbose   Include additional messages that might help when problems occur.

The subcommand user password set sets the password of a user.

set - Set the password a user (ECS containers only).

  Usage:
        set [username] [password]

  Positional Variables:
        username   Login name of the user. (Required)
        password   Password of the user. (Required)

  Flags:
       --version   Displays the program version string.
    -h --help      Displays help with available flag, subcommand, and positional value parameters.
       --ecs-in    The ECS container (unencrypted, instead of stdin).
       --ecs-out   File receiving the updated ECS container (unencrypted, instead of stdout).
       --verbose   Include additional messages that might help when problems occur.

The subcommand user password verify verifys the password of a user. Depending on the outcome of the verification the exit code can be one of the following:

• 0 : The specified password is correct.
• 1 : The specified password is not correct.
• any other : An error occurred.

verify - Verify the password of a user (ECS containers only).

  Usage:
        verify [username] [password]

  Positional Variables:
        username   Login name of the user. (Required)
        password   Password of the user. (Required)

  Flags:
       --version   Displays the program version string.
    -h --help      Displays help with available flag, subcommand, and positional value parameters.
       --ecs-in    The ECS container (unencrypted, instead of stdin).
       --verbose   Include additional messages that might help when problems occur.

Subcommand: condition

The condition subcommand provides access to conditioning and conversion. Conditioning takes a configuration file, parses the configuration and writes the configuration properly formatted. Conversion actually conditions a configuration and writes it using a different format (ATV or ECS). This way an ATV file that was originally created for use with the mGuard web interface can be converted to an ECS file that can be used to configure an mGuard via SDCard and vice versa.

By default the ECS container to work on is expected to be passed via stdin to ease scripting without generating temporary files. The output of the operation is an unencrypted ECS container that is written to stdout. Optionally input and output can be regular files as well by specifying --in, --atv-out and --ecs-out appropriately.

If an ATV file is passed in and an ECS container is written the conditioned ATV file is stored in the ECS container and the missing parts in the ECS container are initialized with defaults. The defaults are the same a new mGuard comes with. If an ECS container is passed in and an ATV file is written, the configuration stored in the ECS container is simply extracted and saved as an ATV file.

condition - Condition and/or convert a mGuard configuration file

  Flags:
       --version   Displays the program version string.
    -h --help      Displays help with available flag, subcommand, and positional value parameters.
       --in        File containing the mGuard configuration to condition (ATV format or ECS container)
       --atv-out   File receiving the conditioned configuration (ATV format, instead of stdout)
       --ecs-out   File receiving the conditioned configuration (ECS container, unencrypted, instead of stdout)
       --verbose   Include additional messages that might help when problems occur.

Subcommand: merge

The merge subcommand merges two configuration files into one. The first specified file is taken as the base for the result, then the configuration stored in the second file is "stacked" upon the first configuration. Simple values are overwritten. Table values (lists) are merged depending on their row id. Rows with the same row id are overwritten, other rows are appended to the table. If the first file is an ATV file, it is implicitly converted to an ECS file first. Therefore the resulting ECS container contains default settings for all elements except the encorporated mGuard configuration (/aca/cfg).

If the second configuration file has a lower version than the first one, the mGuard-Config-Tool trys to migrate the second configuration up to the version of the first configuration file. If the second configuration file has a higher version than the first configuration file, merging will be aborted. The migrations are implemented in all conscience, but they are not complete. The merged configuration must be tested thoroughly before bringing it in production. Please also see the known limitations below.

By default all settings are merged from the second configuration into the first configuration. Optionally you can merge selectively by specifying a merge configuration using --config. The merge configuration is just a list of settings that should be merged. At present only top-level settings are supported. Everything behind a # character is treated as a comment (example).

By default the output of the operation is an unencrypted ECS container that is written to stdout. The output can be written to a regular file as well by specifying --ecs-out and --atv-out appropriately.

merge - Merge two mGuard configuration files into one

  Usage:
	merge [1st-file] [2nd-file]

  Positional Variables: 
	1st-file   First configuration file to merge (Required)
	2nd-file   Second configuration file to merge (Required)

  Flags: 
       --version   Displays the program version string.
    -h --help      Displays help with available flag, subcommand, and positional value parameters.
       --config    Merge configuration file
       --atv-out   File receiving the merged configuration (ATV format)
       --ecs-out   File receiving the merged configuration (ECS container, unencrypted, instead of stdout)
       --verbose   Include additional messages that might help when problems occur.

Subcommand: encrypt

The encrypt subcommand encrypts a configuration, so only the mGuard with the specified serial number is able to read it. The mGuard-Config-Tool connects to the mGuard device database to retrieve the device certificate for the mGuard and encrypts the passed ECS container using S/MIME encryption. The encrypted container cannot be opened by the mGuard-Config-Tool after it any more, so encrypting an ECS container should be the last step.

It might be desirable to cache downloaded certificates locally to improve performance and circumvent possible connectivity issues. Therefore you may specify --cache to instruct the mGuard-Config-Tool to drop downloaded certificates into the specified directory and look for needed certificates there first, before trying to download them again.

By default the unencrypted ECS container to work on is expected to be passed via stdin to ease scripting without generating temporary files. The output of the operation is an encrypted ECS container that is written to stdout. The output can be written to a regular file as well by specifying --ecs-out appropriately.

encrypt - Encrypt a mGuard configuration for a mGuard with a specific serial number (requires device database access)

  Usage:
	encrypt [serial]

  Positional Variables: 
	serial   Serial number of the mGuard (Required)

  Flags: 
       --version   Displays the program version string.
    -h --help      Displays help with available flag, subcommand, and positional value parameters.
       --in        File containing the mGuard configuration to encrypt (ATV format or unencrypted ECS container)
       --ecs-out   File receiving the encrypted configuration (ECS container, encrypted, instead of stdout)
       --cache     Directory where certificates are cached
       --verbose   Include additional messages that might help when problems occur.

Subcommand: service **WINDOWS ONLY**

The service subcommand provides access to the Configuration Preparation Service (CPS). The CPS is part of the mGuard-Config-Tool, stays in the background and monitors a specific directory for ATV/ECS files (hot-folder technique). As soon as a new ATV/ECS file is dropped into the hot-folder, the service merges a specific mGuard base configuration with the dropped configuration and generates ATV/ECS files with the merged configuration. The dropped ATV/ECS files must not be encrypted to allow the service to process it. The service generates a zip file containing everything that is needed to flash a specific firmware and to load an initial configuration into a mGuard device. This is particularly useful when preparing mGuards in production and allows to run (and update) the mGuard-Config-Tool on a server.

Installing / Uninstalling and Controlling the Service

The install and uninstall subcommand installs respectively uninstalls the mGuard-Config-Tool as a windows service. The start and stop subcommands communicate with the Service Control Manager (SCM) to start/stop the installed service. As for all services, the usual service control panel (services.msc) can also be used. The debug subcommand runs the service without installation and is used for debugging purposes only.

By default the service is registered to run as LocalSystem which means that it runs with administrative rights on the machine it is installed on. This ensures that you do not run into permission issues when running it locally, but you are strongly encouraged to create a service account with the minimum rights the service needs to access the configured directories. This step is also required when working with shared folders on a network as LocalSystem is often not allowed to access file shares.

service - Controls the mGuard Configuration Preparation Service (CPS)

  Usage:
	service [install|uninstall|start|stop|debug]

  Subcommands: 
    install     Install the windows service
    uninstall   Uninstall the windows service
    start       Start the installed windows service
    stop        Stop the installed windows service
    debug       Run as a command line application for debugging purposes

  Flags: 
       --version   Displays the program version string.
    -h --help      Displays help with available flag, subcommand, and positional value parameters.
       --verbose   Include additional messages that might help when problems occur.

Configuring the Service

The service can be configured using a YAML configuration file that is expected beside mguard-config-tool.exe. It must be named mguard-config-tool.yaml. The default configuration is generated in the first run, if permissions allow that. The default configuration file looks like the following:

cache:
  path: ./data/cache                               # directory: cache for various files (e.g. downloaded certificates)
input:
  base_configuration:
    path: ./data/configs/default.atv               # file: base configuration (usually an ATV file)
  merge_configuration:
    path: ./data/configs/mguard-secure-cloud.merge # file: merge configuration (empty => merge all settings)
  hotfolder:
    path: ./data/input                             # directory: the hot-folder that is monitored for ATV/ECS files to process
  passwords:
    root: ""                                       # password for user 'root' (empty => do not touch the password)
    admin: ""                                      # password for user 'admin' (empty => do not touch the password)
  sdcard_template:
    path: ./data/sdcard-template                   # directory: basic sdcard structure (with firmware files)
output:
  merged_configurations:
    path: ./data/output-merged-configs             # directory: merged configurations are put here
    write_atv: true                                # controls whether to generate an ATV file with the merged configuration (true, false)
    write_unencrypted_ecs: true                    # controls whether to generate an unencrypted ECS file with the merged configuration (true, false)
    write_encrypted_ecs: true                      # controls whether to generate an encrypted ECS file with the merged configuration (true, false)
  update_packages:
    path: ./data/output-update-packages            # directory: update packages with firmware and the merged configuration are put here
    configuration: encrypted_ecs                   # configuration to put into the update package (atv, unencrypted_ecs, encrypted_ecs)
tools:
  openssl:
    path: ""                                       # file: openssl executable (empty => search the PATH variable for the executable)

The configured directories are created, if necessary and permissions allow that. Before the service can run, the base configuration file and the SDCard template files must be provided in the configured directories. If the base configuration or the SDCard template files are missing, the service will fail to start.

The update package is a zip file that contains all files that need to be copied to a SDCard to flash the mGuard to the desired version and install the merged configuration. Depending on the output.update_packages.configuration setting in the service configuration an ATV file (Rescue Config/preconfig.atv), an unencrypted ECS container (ECS.tgz) or an encrypted ECS container (<serial>.ecs.p7e) is deployed. The preconfiguration script (Rescue Config/preconfig.sh) that is executed after the firmware has been flashed successfully is generated from a template (Rescue Config/preconfig.sh.tmpl) and tailored to the needs of the chosen configuration. When editing preconfig.sh.tmpl you MUST ensure that you use LF line endings. Using CRLF (windows standard) renders the script unexecutable!

File Name Conventions

The name of the ATV/ECS files dropped into the hot-folder must match a specific pattern to get processed. The pattern depends on whether the service has to generate encrypted ECS containers. If the service generates unencrypted ECS containers or no ECS containers at all, the pattern is *.(atv|ecs|tgz). If the service is configured to generate encrypted ECS containers the pattern includes the serial number of the mGuard and is <serial>.(atv|ecs|tgz). The serial number uniquely identifies mGuard devices and allows the service to retrieve the appropriate device certificates that are needed to encrypt generated ECS files for specific mGuards.

The name of generated files consist of the basename of the dropped file (without extension) plus a timestamp. For example, if you drop a file named myconfig.atv into the hotfolder at 2020/01/01 15:01:30 the service will create the following files, if it is configured to do so:

• Merged configuration (ATV): myconfig (20200101150130).atv
• Merged configuration (ECS unencrypted): myconfig (20200101150130).ecs
• Merged configuration (ECS encrypted): myconfig (20200101150130).ecs.p7e
• Update Package: myconfig (20200101150130).zip

Beware!

ATV files and unencrypted ECS containers contain unencrypted secrets like VPN certificates. Furthermore using ATV files implies setting passwords in plaintext! Therefore the most secure way to get a configuration into a mGuard is to use the encrypted ECS container. ATV files and unencrypted ECS containers should only be used when there is an issue with accessing the device database to retrieve mGuard device certificates needed to generate encrypted ECS containers.

Known Limitations

• Comments: Reading a configuration file discards comments, so a written configuration file does not contain any comments.
• Migrations: Only a selection of migrations is implemented to make our own use cases work. The lack of documentation about ATV documents and migrations forced us to deduce needed migration steps from observed behavior. If you discover further steps that are needed to migrate from one version to another, please let us know by opening an issue.

Issues and Contributions

As mGuard-Config-Tool is not a project of PHOENIX CONTACT, please don't request help for it there!

If you encounter problems using mGuard-Config-Tool, please file an issue.

If you have an idea on how to improve mGuard-Config-Tool, please also file an issue. Pull requests are also very appreciated. In case of major changes, please open an issue before to discuss the changes. This helps to coordinate development and avoids wasting time.