Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use, which are available at Stonebranch Integration Hub - 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 files while keeping the PGP keys in the UDMG keystore.

Version Information

Template Name	Extension Name	Version	Status
UDMG OpenPGP v2	ue-udmg-openpgp-v2	v2 (Current 2.0.1)	Fixes and new Features are introduced.
UDMG OpenPGP	ue-udmg-openpgp	v1	End of Support
MFT PGP	ue-mft-pgp	v1	End of Support

Refer to the Changelog for version history information.

UDMG OpenPGP v2 is a Major Version Update! Customers using UDMG OpenPGP should migrate to UDMG OpenPGP v2 to be properly supported. UDMG OpenPGP v2 when imported is not replacing UDMG OpenPGP allowing for a step-by-step migration of tasks in production systems.

Software Requirements

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

Area	Details
Python Version	Requires Python 3.7 or 3.11. Tested with 3.7.16 and 3.11.6
Universal Agent	Both Windows and Linux agents are supported: Universal Agent for Windows x64 Version 7.5.0.0 and later. Universal Agent for Linux Version 7.5.0.0 and later.
Universal Controller	Universal Controller Version 7.5.0.0 and later.
Network and Connectivity	The Universal Agent needs to have connectivity to the UDMG API endpoint. UDMG version supported is 1.2.0.0 and later.

Key Features

Feature	Description
Encrypt single or multiple files.	Encrypt a single or multiple files with the public PGP key of the intended recipient.
Decrypt single or multiple files.	Decrypt a single or multiple files with the private PGP key of the intended recipient.
Signing with Encryption	Encrypt a single or multiple files with the public PGP key of the intended recipient and sign with the private key of the sender.
Signature Verification with Decryption	Decrypt a single or multiple files with the private PGP key of the intended recipient and verify the signature with the public key of the sender.
File Management	Source file(s) can be deleted after processing. Source file(s) can be archived to a specific folder after processing.
Key Management	PGP private and public keys are stored and retrieved online from UDMG, without keeping them in files or keyrings on the Agent host.
Binary or ASCII armored format	Support for Binary and ASCII armored formats.
OpenPGP compliant	Internal encryption handling without the need for external tools.

Supported Actions

Action: “Encrypt File” or “Encrypt Multiple Files”

Encrypt a single file or multiple files with the public PGP key of the intended recipient. Signing with the sender’s private key can be performed. The PGP keys are selected by the key names as stored in the UDMG PGP Key Store.

Configuration examples

Scenario A

Encrypt a single file without signing and archive the source file.

Scenario B

Encrypt multiple files without signing them and stop the file processing when an error occurs.

Scenario C

Encrypt multiple files, sign them, and continue the file processing when an error occurs.

UDMG Keys

Action Output

Output Type

Description

Example (Successful Execution)

EXTENSION

The extension output provides the following information:

“exit_code“, “status“, “status_description“: General info regarding the task execution.
“invocation” > “fields”: The task configuration used for this task execution.
“result” > “metadata”: Metadata information.
- > “count”: Number of file entries present in “result” > “Files”.
- > “input_file_count”: Number of files identified for encryption or decryption.
- > “success_count”: Number of files successfully encrypted or decrypted.
- > “failure_count”: The number of files failed to be encrypted or decrypted.
- > “warning_count”: The number of files encrypted or decrypted with a warning.
- > “skip_count”: Number of files skipped to be processed due to previous error.
“result” > “Files”: A list that contains information on Files excluding the files skipped due to previous errors.
- “source_file”: The source file path.
- “target_file”: The target file path.
- “archived_file” The archive file path, in case of successful encryption/decryption.
- “embedded_filename”: The original filename that is embedded in the PGP message, if any. It is null in case of encryption actions.
- “status”: The status of the operation on the specific file. Possible values (success | failure | warning).
- “message”: The warning or error message.

Successful Execution

{
    "exit_code": 0,
    "status_description": "Task executed successfully",
    "invocation": {
        "extension": "ue-udmg-openpgp-v2",
        "version": "2.0.1",
        "fields": {
            .....
        }
    },
    "result": {
        "metadata": {
            "count": 2,
            "input_file_count": 2,
            "success_count": 2,
            "failure_count": 0,
            "warning_count": 0,
            "skip_count": 0
        },
        "files": [
            {
                "source_file": "/source_directory/pgp_test1.txt",
                "target_file": "/target_directory/pgp_test1.txt.asc",
                "archived_file": "/archive_directory/pgp_test1.txt",
                "embedded_filename": null,
                "status": "success"
                "message": null
            },
            {
                "source_file": "/source_directory/pgp_test2.txt",
                "target_file": "/target_directory/pgp_test2.txt.asc",
                "archived_file": "/archive_directory/pgp_test2.txt",
                "embedded_filename": null,
                "status": "success"
                "message": null
            }
        ]
    }
}

Failed Execution

{
    "exit_code": 1,
    "status_description": "insecure cipher not allowed: < Error Description >",
    "invocation": {
        "extension": "ue-udmg-openpgp-v2",
        "version": "2.0.1",
        "fields": {
            "action": "Encrypt Multiple Files",
            "fail_on_error": True,
            .....
        }
    },
    "result": {
        "metadata": {
            "count": 3,
            "input_file_count": 4,
            "success_count": 1,
            "failure_count": 1,
            "warning_count": 1,
            "skip_count": 1
        },
        "files": [
            {
                "source_file": "/source_directory/pgp_test1.txt",
                "target_file": "/target_directory/pgp_test1.txt.asc",
                "archived_file": "/archive_directory/pgp_test.txt",
                "embedded_filename": null,
                "status": "success"
                "message": null
            },
            {
                "source_file": "/source_directory/pgp_test2.txt",
                "target_file": "/target_directory/pgp_test2.txt.asc",
                "archived_file": "/archive_directory/pgp_test2.txt",
                "embedded_filename": null,
                "status": "warning"
                "message": "None of the preferred compression algorithms is supported"
            },
            {
                "source_file": "/source_directory/pgp_test3.txt",
                "target_file": null,
                "archived_file": null,
                "embedded_filename": null,
                "status": "failure"
                "message": "insecure cipher not allowed: < Error Description >"
            }
        ]
    }
}

STDOUT

empty

STDERR

At the start of the task execution, if the action is “Encrypt Multiple Files” or “Decrypt Multiple Files” and is run with at least INFO debug level, a list of all matched files is printed.
If the task is run with at least debug level INFO messages are printed in relation to the processing of the files.
In case an error occurs, “Fail on First Error” is enabled and the task is run with at least INFO debug level, a message regarding the skip of the remaining files will be printed.

Action: “Decrypt File” or “Decrypt Multiple Files”

Decrypt a single or multiple files with the private PGP key of the intended recipient. Verification of the file's signature with the sender's public key can also be performed. The PGP keys are selected by the key names as stored in the UDMG PGP Key Store.

Configuration examples

Scenario A

Decrypt a single file and verify the file’s signature.

Scenario B

Decrypt multiple files and stop the file processing if an error occurs. Delete the source files after file processing.

Action Output

The actions' output is the same as the output of actions “Encrypt File” and “Encrypt Multiple Files”.

Input Fields

Field	Type	Description	Version Information
Action	Choice	The action performed upon the task execution. Available actions: Encrypt a File (default) Encrypt Multiple Files Decrypt a File Dectypr Multiple Files	Introduced in 1.0.0 Modified in 2.0.0
Armor	Boolean	If selected, an encrypted file will be generated in an ASCII-armored format. Else in binary format. Only available for actions “Encrypt a File” and “Encrypt Multiple Files”. The default is true.	Introduced in 1.0.0
UDMG Server	Text	UDMG Server URL. Example: http://udmgserver.company.com:8080/api/	Introduced in 1.0.0
UDMG Credentials	Credentials	UDMG Server Credentials. The Credentials definition should be as follows. User Name as "Runtime User". User Password as "Runtime Password". The user must have read permissions for PGP keys.	Introduced in 1.0.0
File	Text	Full Path of the input file: Example: /home/users/user1/myfile. Only available for actions “Encrypt a File” and “Decrypt a File”.	Introduced in 1.0.0
Output File	Text	Full Path of Output File. If not provided, the file is created in the same directory as the input file: “Encrypt a File”: Add .pgp or .asc to the input filename. “Decrypt a File”: It is assumed that the input file has either .pgp or .asc suffix. The suffix is removed.	Introduced in 1.0.0
Filename Pattern	Text	Filename pattern, inclusive of the source directory where files are located. Unix shell wildcards can be used. Example: /users/homeuser/files/*gpg Only available for actions “Encrypt Multiple Files” and “Decrypt Multiple Files”.	Introduced in 2.0.0
Output Directory	Text	The Output Directory in case multiple files are Encrypted or Decrypted. Filename suffix .pgp or .asc is added or removed accordingly. If not provided, the files are created in the same directory as the input files: Only available for actions “Encrypt Multiple Files” and “Decrypt Multiple Files”. The new filenames on the output directory are constructed as follows: “Encrypt Multiple Files”: Add .pgp or .asc to the input filenames. “Decrypt Multiple Files”: Remove .pgp or .asc suffix if present.	Introduced in 2.0.0
Public Key	Dynamic Choice	Name of the PGP key record on the UDMG keystore that contains the public key. Only available for actions “Encrypt a File” and “Encrypt Multiple Files”.	Introduced in 1.0.0 Modified in 2.0.0
Private Key	Dynamic Choice	Name of the PGP key record on the UDMG keystore that contains the private key and passphrase. Only available for actions “Decrypt a File” or “Decrypt Multiple Files”.	Introduced in 1.0.0 Modified in 2.0.0
Post Action	Choice	Action performed upon the task execution for the files that managed to get encrypted or decrypted successfully. Else they will remain on the source directory. Available Post Actions: Empty Archive Delete	Introduced in 1.0.0
Archive Path	Text	Archive directory where the input file or files are moved after processing. Only for Post Action “Archive”.	Introduced in 1.0.0
Sign	Boolean	Sign the document with a private PGP key. Only available for actions “Encrypt a File” and “Encrypt Multiple Files”. The default is false.	Introduced in 1.0.0
Private Signing Key	Dynamic Choice	Name of the PGP key record on the UDMG keystore that contains the private key for the signing. Dynamic Choice field populated with the list of private PGP keys accessible to the UDMG user. Only if Sign is selected.	Introduced in 1.0.0
Verify	Boolean	Verify the signature with a public PGP key. Only available for actions “Decrypt a File” and “Decrypt Multiple Files”. The default is false.	Introduced in 1.0.0
Public Verification Key	Dynamic Choice	Name of the PGP key record on the UDMG keystore that contains the public key for the signature verification. Dynamic Choice field populated with the list of public PGP keys accessible to this UDMG user. Only if Verify is selected.	Introduced in 1.0.0
Fail on First Error	Boolean	Flags the task to fail on the first error occurred. Only available for actions “Encrypt Multiple Files” and “Decrypt Multiple Files”. The default is true.	Introduced in 2.0.0

Cancelation and Rerun

Rerunning the extension won’t cause any problems. When creating or archiving files the extension overrides preexisting ones.

Exit Codes

Exit Code	Status	Status Description	Meaning
0	Success	“Task executed successfully.“	Successful Execution.
1	Failed	“Execution Failed: <<Error Description>>”	This exit code is used in case of failure and in case no other failure exit code is applicable.
2	Failed	“Authentication Error: Account cannot be authenticated.“	UDMG: Bad credentials.
3	Failed	“Authorization Error: Account is not authorized to perform the requested action.“	UDMG: Insufficient permissions.
10	Failed	“Connection Error: <<Error Description>>“	UDMG: Bad connection data or connection timed out.
11	Failed	“Connection Error: 404 page not found.“	Invalid UDMG API endpoint.
20	Failed	“Data Validation Error: <<Error Description>>“	Input fields validation error.
100	Success	“Execution warning: At least one file processing ended up with a warning.“	At least one file process finished with a warning.
101	Success	“Execution warning: At least one file processing failed.“	At least one file process failed.
102	Failed	“Execution Failed: All file processes have failed.”	All file processes failed.

STDOUT and STDERR

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

How To

Import Universal Template

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

This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.
To import the Universal Template into your Controller, follow these instructions.
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.

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, concerning 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 reliable sources for determining the success or failure of a task.

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

Document References

This document references the following documents:

Document Link	Description
Universal Templates	User documentation for creating, working with, and understanding Universal Templates and Integrations.
Universal Tasks	User documentation for creating Universal Tasks in the Universal Controller user interface.
Credentials	User documentation for creating and working with credentials.
Resolvable Credentials Permitted Property	User documentation for Resolvable Credentials Permitted Property.
PGP Key Management (UDMG Server CLI)	Management of PGP keys with the command line interface.
PGP Key Management (UDMG Server Web Services)	Management of PGP keys with the web services.

Changelog

ue-udmg-openpgp-2.0.1 (2024-05-02)

Fixes

Fixed: Resolved compatibility issues with Linux systems utilizing glibc version 2.17 (#36654).
Fixed: Error Code 101 now correctly corresponds to a task failure (#36477).

ue-udmg-openpgp-2.0.0 (2024-02-05)

Deprecations and Breaking Changes

Deprecation: “UDMG OpenPGP” is deprecated and replaced by “UDMG OpenPGP v2”.
Breaking Change: Minimum universal agent and controller version set to 7.5.

Enhancements

Added: Functionalities inherited from UDMG OpenPGP with the addition of Encryption and Decryption of multiple Files #(35553).
Added: Integration no longer has dependent libraries as they are now bundled within it (#35542).
Added: Extension Output is enhanced with more information and is also available in case of failure (#35554).
Added: Exit codes simplified. PGP Error codes are removed as more information exists on the Extension Output (#35551).

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

Added: Ability to sign messages during encryption. (#32816)
Added: Ability to verify the message’s signature during decryption. (#32816)
Added: Use preferred cipher algorithm from the 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