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

Template Name	Extension Name	Extension Version

Template Name	Extension Name	Extension Version
UDMG OpenPGP	ue-udmg-openpgp	1.0.0

Refer to Changelog for version history information.

Note

The UDMG PGP Universal Extension (ue-mft-pgp) is deprecated and replaced by UDMG OpenPGP (ue-udmg-openpgp)

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.

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 the instructions here.
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.

Field	Input type	Default value	Type	Description

Field	Input type	Default value	Type	Description
Action	Required	Encrypt	Choice	Action performed upon the task execution. Available actions: Encrypt Decrypt
Armor	Optional	true	Boolean	Encode using ASCII Armor format. Only for Action Encrypt
UDMG Server	Required	-	Text	UDMG Server URL. For example: http://localhost:18080/api
UDMG Credentials	Required	-	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
File	Required	-	Text	The name of the input file
Output File	Optional	-	Text	The name of the output file. If not provided, the file is extracted in the Runtime Directory and the name is constructed as: Encrypt: add .pgp or .asc to the input filename Decrypt: it is assumed that input file has either .pgp or .asc suffix, remove this suffix .
Public Key	Required	-	Text	Name of the PGP key record on UDMG keystore that contains the public key. Dynamic Choice field populated with the list of public PGP keys accessible to this UDMG user. Only for Action Encrypt
Private Key	Required	-	Text	Name of the PGP key record on UDMG keystore that contains the private key and passphrase. Dynamic Choice field populated with the list of private PGP keys accessible to this UDMG user. Only for Action Decrypt
Post Action	Optional	-- None--	Choice	Action performed upon the task execution. Available actions: -- None -- Archive Delete
Archive Path	Required	-	Text	Archive directory where the input file is moved to after processing Only for Post Action Archive
Sign	Optional	false	Boolean	Sign the document with a private PGP key. Only for Action Encrypt
Private Signing Key	Optional	-	Dynamic Choice	Name of the PGP key record on UDMG keystore that contains the private key for the signing. Dynamic Choice field populated with the list of private PGP keys accessible to this UDMG user. Only if Sign is selected
Verify	Optional	false	Boolean	Verify the signature with a public PGP key. Only for Action Decrypt
Public Verification Key	Optional	-	Dynamic Choice	Name of the PGP key record on 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

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.

Exit Code	Status Classification Code	Status Classification Description	Status Description

Exit Code	Status Classification Code	Status Classification Description	Status Description
0	SUCCESS	Successful Execution	SUCCESS
1	FAIL	Failed Execution	FAIL: < Error Description >
2	AUTHENTICATION_ERROR	Bad credentials	AUTHENTICATION_ERROR: Account cannot be authenticated.
3	AUTHORIZATION_ERROR	Insufficient Permissions	AUTHORIZATION_ERROR: Account is not authorized to perform the requested action.
10	CONNECTION_ERROR	Bad connection data or connection timed out	CONNECTION_ERROR: < Error Description >
11	CONNECTION_ERROR	Invalid UDMG API endpoint	CONNECTION_ERROR: 404 page not found
20	DATA_VALIDATION_ERROR	Input fields Validation Error	DATA_VALIDATION_ERROR: < Error Description > ** See STDERR for more detailed error descriptions.
21	PGP_ERROR	PGP Processing error	PGP_ERROR: general error during processing: < Error Description >
22	PGP_ERROR	PGP Processing Error	PGP_ERROR: error during encryption: < Error Description >
23	PGP_ERROR	PGP Processing Error	PGP_ERROR: error during decryption: < Error Description >
30	PGP_ERROR	PGP Processing Error	PGP_ERROR: SSL cipher not supported: < Error Description >
31	PGP_ERROR	PGP Processing Error	PGP_ERROR: insecure cipher not allowed: < Error Description >
32	PGP_ERROR	PGP Processing Error	PGP_ERROR: not implemented feature: < Error Description >
40	PGP_ERROR	PGP Processing Error	PGP_ERROR: Verification failed: No signature found
41	PGP_ERROR	PGP Processing Error	PGP_ERROR: Verification failed: Wrong signature
100	SUCCESS	Successful Execution with Warning	SUCCESS: Encryption success but not using the PGP key preferred settings `SUCCESS: MFT Encrypt executed successfully with warning: none of the preferred compression algorithms is supported` `SUCCESS: MFT Encrypt executed successfully with warning: none of the preferred cipher algorithms is supported` `SUCCESS: MFT Encrypt executed successfully with warning: none of the preferred compression and cipher algorithms is supported`

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:

Attribute	Type	Description

Attribute	Type	Description
encrypted_file	string	The name of the file that is encrypted, the input file for Decrypt action, the output file for Encrypt action
decrypted_file	string	The name of the file that is not encrypted, the output file for Decrypt action, the input file for Encrypt action
embedded_filename	string	The original filename that is embedded in the pgp message, if any

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.

Document Link	Description

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-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)

UDMG OpenPGP