UDMG PGP


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 NameExtension NameExtension Version
UDMG PGPue-mft-pgp1.1.1

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.0 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 perating system flavor and version.

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.

Key Features

This Universal Extension provides the following key features:

  • Actions
    • Encrypt a file.
    • Decrypt a file.
  • File Management
    • Source file can be deleted after processing.
    • Source file can be archived to a specific after processing.
  • Key Management
    • PGP keys are retrieved online from UDMG without keeping them in files or keyrings.
  • Other
    • Binary or ASCII armored format.
    • Internal encryption without the need for GPG 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.

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.

FieldInput typeDefault valueTypeDescription
ActionRequiredEncryptChoiceAction performed upon the task execution.
Available actions:
  • Encrypt
  • Decrypt
ArmorOptionaltrueBooleanOnly for Action Encrypt
MFT ServerRequired-TextUDMG Server URL.
For example: http://localhost:8080/api
MFT CredentialsRequired-CredentialsUDMG 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
FileRequired-TextThe name of the input file
Output FileOptional-TextThe 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 KeyRequired-TextName of the PGP key record on UDMG keystore that contains the public key.
Only for Action Encrypt
Private KeyRequired-TextName of the PGP key record on UDMG keystore that contains the private key and passphrase.
Only for Action Decrypt
Post ActionOptional-- None--ChoiceAction performed upon the task execution.
Available actions:
  • -- None --
  • Archive>
  • Delete
Archive PathRequired-TextArchive directory where the input file is moved to after processing
Only for Post Action Archive

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 CodeStatus Classification CodeStatus Classification DescriptionStatus Description
0SUCCESSSuccessful ExecutionSUCCESS
1FAILFailed ExecutionFAIL: < Error Description >
2AUTHENTICATION_ERRORBad credentialsAUTHENTICATION_ERROR: Account cannot be authenticated.
3AUTHORIZATION_ERRORInsufficient PermissionsAUTHORIZATION_ERROR: Account is not authorized to perform the requested action.
10CONNECTION_ERRORBad connection data or connection timed outCONNECTION_ERROR: < Error Description >
11CONNECTION_ERRORExtension specific connection errorCONNECTION_ERROR: 404 page not found
20DATA_VALIDATION_ERRORInput fields Validation ErrorDATA_VALIDATION_ERROR: 400 bad request:
21PGP_ERRORPGP processing errorPGP_ERROR: general error during processing: []
22PGP_ERRORPGP processing ErrorPGP_ERROR: error during encryption: []
23PGP_ERRORPGP processing ErrorPGP_ERROR: error during decryption: []
30PGP_ERRORPGP processing ErrorPGP_ERROR: SSL cipher not supported: []
31PGP_ERRORPGP processing ErrorPGP_ERROR: insecure cipher not allowed: []
32PGP_ERRORPGP processing ErrorPGP_ERROR: not implemented feature: []
100SUCCESSSuccessful Execution with WarningSUCCESS: Encryption success but not using any of the preferred compression algorithms

See description of the Transfer Error Code: https://doc.waarp.org/waarp-gateway/0.7.1/fr/reference/errorcodes.html

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:

AttributeTypeDescription
encrypted_filestringThe name of the file that is encrypted,
the input file for Decrypt action, the output file for Encrypt action
decrypted_filestringThe name of the file that is not encrypted,
the output file for Decrypt action, the input file for Encrypt action
embedded_filenamestringThe original filename that is embedded in the gpg message, if any

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

{
    "exit_code": 0,
    "status_description": "SUCCESS: MFT Encrypt executed successfully!",
    "changed": true,
    "invocation": {
        "extension": "ue-mft-pgp",
        "version": "1.0.0",
        "fields": {
            "action": "Encrypt",
            "mft_server": "http://localhost:9180/api",
            "credentials_username": "****",
            "credentials_password": "****",
            "input_file": "/atests/testdata/export.md",
            "output_file": "",
            "private_key_name": null,
            "public_key_name": "test1.pub",
            "post_action": null,
            "archive_path": null,
            "armor": true,
            "use_embedded_filename": true
        }
    },
    "result": {
        "files": [
            {
                "encrypted_file": "/atests/testdata/export.md.asc",
                "decrypted_file": "/atests/testdata/export.md",
                "embedded_filename": null
            }
        ]
    }
}


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

{
    "exit_code": 0,
    "status_description": "SUCCESS: MFT Decrypt executed successfully!",
    "changed": true,
    "invocation": {
        "extension": "ue-mft-pgp",
        "version": "1.0.0",
        "fields": {
            "action": "Decrypt",
            "mft_server": "http://localhost:9180/api",
            "credentials_username": "****",
            "credentials_password": "****",
            "input_file": "/atests/testdata/export.md.asc",
            "output_file": "export.txt",
            "private_key_name": "test1.key",
            "public_key_name": null,
            "post_action": "Delete",
            "archive_path": null,
            "armor": false,
            "use_embedded_filename": true
        }
    },
    "result": {
        "files": [
            {
                "encrypted_file": "/atests/testdata/export.md.asc",
                "decrypted_file": "export.txt",
                "embedded_filename": "export.md"
            }
        ]
    }
}

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.

Document References

This document references the following documents.

Document LinkDescription
Universal TemplatesUser documentation for creating, working with and understanding Universal Templates and Integrations.
Universal TasksUser documentation for creating Universal Tasks in the Universal Controller user interface.
CredentialsUser documentation for creating and working with credentials.
Resolvable Credentials Permitted PropertyUser 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-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