Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use, which are available at https://www.stonebranch.com/integration-hub/Terms-and-Privacy/Terms-of-Use/

Overview

UDMG (Universal Data Mover Gateway) is a business-to-business MFT (Managed File Transfer) Solution. It provides the capabilities to securely manage File transfers with external business partners (i.e. Customers or Suppliers), and between any endpoint in today’s Hybrid-IT infrastructure, on-premises, or in the cloud (public and or private). It also comes up with a keystore for PGP public and private keys.

This Universal Extension provides the capability to perform OpenGPG encryption and decryption on a file while keeping the PGP keys in the UDMG keystore.

Version Information

Refer to Changelog for version history information.

Software Requirements

This integration requires a Universal Agent and a Python runtime to execute the Universal Task.

Software Requirements for Universal Template and Universal Task

Requires Python 3.7.6 or higher.

Requires bz2 python library and the Cryptography and CFFI python modules. For bz2 support on Linux, the following package must be installed bzip2-devel or libbz2-dev, the exact name depends on the operating system flavor and version.
For CFFI on Linux, the libffi.so.6 must be installed. For the systems that do not provide it, please refer to Libffi.so.6()(64bit) Download for Linux (rpm) or RPM resource libffi.so.6()(64bit).

Tested with the Universal Agent bundled Python distribution which provides all required dependencies.

Software Requirements for Universal Agent

Both Windows and Linux agents are supported.

• Universal Agent for Windows x64 Version 7.3.0.0 and later with python options installed.
• Universal Agent for Linux Version 7.3.0.0 and later with python options installed.

Software Requirements for Universal Controller

Universal Controller Version 7.3.0.0 and later.

Network and Connectivity Requirements

Universal Agent requires connectivity towards the UDMG server REST API.

UDMG 1.2.0.0 and later.

Key Features

This Universal Extension provides the following key features:

• Actions
  • Encrypt a single file with the public PGP key of the intended recipient.
  • Decrypt a single file with the private PGP key of the intended recipient.
• Signing and Verification
  • Encrypt a single file with the public PGP key of the intended recipient and sign with the private key of the sender.
  • Decrypt a single file with the private PGP key of the intended recipient and verify the signature with the public key of the sender.
• File Management
  • Source file can be deleted after processing.
  • Source file can be archived to a specific folder after processing.
• Key Management
  • The PGP keys are retrieved online from UDMG without keeping them in files or keyrings on the Agent host.
  • The PGP keys are selected by the key names as stored in UDMG PGP Key Store.
• Other
  • Support for Binary or ASCII armored format.
  • OpenPGP compliant with internal encryption without the need for an external tool.

Import Universal Template

To use the Universal Template, you first must perform the following steps.

1. This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.

2. To import the Universal Template into your Controller, follow the instructions here.

3. When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.

Modifications of this integration, applied by users or customers, before or after import, might affect the supportability of this integration. For more information refer to Integration Modifications.

Configure Universal Task

For a new Universal Task, create a new task, and enter the required input fields.

Input Fields

The input fields for this Universal Extension are described below.

Task Examples

Encrypt a file

Example for encrypting a file:

The configuration on UDMG for the public key:

Decrypt a file

Example for decrypting a file:

The configuration on UDMG for the private key:

Task Output

Output Only Fields

N/A

Exit Codes

The exit codes for this Universal Extension are described below.

Extension Output

In the context of a workflow, subsequent tasks can rely on the information provided by this integration as Extension Output.

Attribute changed is populated as follows"

• false, in case no file was processed.
• true, in case the file was processed.

The Extension output contains attribute result. Attribute result contains the following sub-attributes:

An example of the Extension Output for file encryption is presented below.

{
    "exit_code": 100,
    "status_description": "SUCCESS: Encryption success but not using any of the preferred cipher algorithms",
    "changed": true,
    "invocation": {
        "extension": "ue-udmg-openpgp",
        "version": "1.0.0",
        "fields": {
            "action": "Encrypt",
            "udmg_server": "http://172.31.24.166:9180/api",
            "username": "****",
            "password": "****",
            "input_file": "/atests/pgp_test.txt",
            "output_file": "",
            "private_key": null,
            "public_key": "test8.pub",
            "sign": true,
            "signing_key": "test5.key",
            "verify_signature": false,
            "verification_key": null,
            "post_action": null,
            "archive_path": null,
            "armor": true,
            "use_embedded_filename": true
        }
    },
    "result": {
        "files": [
            {
                "encrypted_file": "/atests/pgp_test.txt.asc",
                "decrypted_file": "/atests/pgp_test.txt",
                "embedded_filename": null
            }
        ]
    }
}

An example of the Extension Output for file decryption is presented below.

{
    "exit_code": 0,
    "status_description": "SUCCESS: MFT Decryption executed successfully!",
    "changed": true,
    "invocation": {
        "extension": "ue-udmg-openpgp",
        "version": "1.0.0",
        "fields": {
            "action": "Decrypt",
            "udmg_server": "http://172.31.24.166:9180/api",
            "username": "****",
            "password": "****",
            "input_file": "/atests/pgp_test.txt.asc",
            "output_file": "/atests/pgp_test.txt.asc-1697068800076322995NIGTT2J5ZL6YH",
            "private_key": "test5.key",
            "public_key": null,
            "sign": false,
            "signing_key": null,
            "verify_signature": true,
            "verification_key": "test8.pub",
            "post_action": null,
            "archive_path": null,
            "armor": false,
            "use_embedded_filename": true
        }
    },
    "result": {
        "files": [
            {
                "encrypted_file": "/atests/pgp_test.txt.asc",
                "decrypted_file": "/atests/pgp_test.txt.asc-1697068800076322995NIGTT2J5ZL6YH",
                "embedded_filename": "pgp_test.txt"
            }
        ]
    }
}

An example of a Set Variable Action to fetch the decrypted file name from the Extension output with a function:

${_outputJsonPath('EXTENSION', '$.result.files[0].decrypted_file')}

See Creating a Set Variable Action within a Task or Workflow and Functions.

STDOUT and STDERR

STDOUT and STDERR provide additional information to User. The populated content can be changed in future versions of this extension without notice. Backward compatibility is not guaranteed.

Integration Modifications

Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.

• Python code modifications should not be done.

• Template Modifications

  • General Section

    • "Name", "Extension", "Variable Prefix", and "Icon" should not be changed.

  • Universal Template Details Section

    • "Template Type", "Agent Type", "Send Extension Variables", and "Always Cancel on Force Finish" should not be changed.

  • Result Processing Defaults Section

    • Success and Failure Exit codes should not be changed.

    • Success and Failure Output processing should not be changed.

  • Fields Restriction Section
    The setup of the template does not impose any restrictions, However with respect to the "Exit Code Processing Fields" section.

    1. Success/Failure exit codes need to be respected.

    2. In principle, as STDERR and STDOUT outputs can change in follow-up releases of this integration, they should not be considered as a reliable source for determining the success or failure of a task.

Event Template configuration related to “Metric Label Attributes” & “Optional Metric Labels” is allowed. However, administrators should be cautious of high cardinality scenarios that might occur

Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.

Document References

This document references the following documents.

Changelog

ue-udmg-openpgp-1.0.0 (2023-10-16)

Deprecations and Breaking Changes

• Deprecation: ue-mft-pgp (UDMG PGP) is deprecated and replaced by ue-udmg-openpgp (UDMG OpenPGP)

Enhancements

• Add: Ability to sign message during encryption. (#32816)

• Add: Ability to verify message’s signature during decryption. (#32816)

• Add: Use preferred cipher algorithm from public key for encryption. (#31295)

• Changed: PGP key template fields from text to dynamic choice. (#32908)

ue-mft-pgp-1.1.1 (2023-02-02)

• Fix: Warning for preferred compression = Uncompressed (#31672)

ue-mft-pgp-1.1.0 (2023-01-31)

• Add: use preferred compression algorithm from public key for encryption. (#31273)
• Add: upgrade PGPy to 0.6 . (#31273)

ue-mft-pgp-1.0.2 (2023-01-12)

• Fix: Correct the handling of binary/ascii mode for GPG message content. (#31308)

ue-mft-pgp-1.0.1 (2022-08-23)

• Initial version