Panel

Table of Contents

maxLevel	2

Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use, which are available at Terms Of Use.

Version Information

Template Name	Extension Name	Version
GnuPG	ue-gnupg	1.0.0

Refer to Changelog for for version history information.

Overview

GnuPG (GPG) is a command line tool implementing the OpenPGP standard. GPG allows for encryption , decryption and signing of data and communications. This integration provides the capability to perform file encryption and decryption, based on GnuPG.

Key Features

Feature	Description
Encrypt	Encrypt files based on file patterns, and optionally sign the encrypted file.
Decrypt	Decrypt files based on file patterns, and optionally verify signature.
Keystore Options	PGP keys can be retrieved from either a local keystore stored on the Universal Agent environment, or from a UDMG based keystore.

Software Requirements

...

Area	Details
Python Version	Requires Python 3.7, tested with Python 3.7.16. and Python 3.11.6.
Universal Agent	Compatible with Universal Agent for Windows x64 and version >= 7.43.0.0. Compatible with Universal Agent for Linux and version >= 7.43.0.0. Only Agents that are Under Support are supported.
Universal Controller	Universal Controller Version >= 7.43.0.0.
GnuPG	This integration requires GnuPG command line tool to be installed manually on the Universal Agent environment. Tested against GnuPG 2.2.19 and 2.4.4.

...

Encrypt a single file or multiple files given a file pattern. Optionally sign the encrypted file(s). Public key for encryption and Private Key for signing, are retrieved from the keystore stored in the locally running GnuPG tool, though fields ‘Local Key' and 'Private Key For Signing' respectively.

Configuration examples

Image Modified

Encrypt and sign a single file, using keys from a keyring file on the local GPG.

User Scenario: Retrieve the single file "finance_report.csv", and encrypt it in ASCII format, using PGP key that exists on a local GPG keyring file, stored in /home/.gnupg directory. After the encryption is completed, sign the encrypted file. Allow the integration to overwrite any existing encrypted file with the same name.

Encrypt and sign multiple files matching a pattern, using keys stored in the default keyring of the local GPG.

User Scenario: Retrieve all matching files based on filename pattern "finance_2*.csv", and encrypt it in ASCII format, using PGP key that exists on the default keyring of the local GPG. After the encryption is completed, sign the encrypted files. The task instance will fail if no matching files are found. It will also stop its execution on the first encryption error. To be proactive, the environment variable 'UE_GNUPG_VERBOSE_OUTPUT' will provide additional information on the STDOUT.

Action Output

Output Type

Description

Example

EXTENSION

The extension output provides the following information:

exit_code, status_description: General info regarding the task execution.
result.metadata.count: Number of files that have been encrypted. Skipped files are not counted here.
result.metadata.input_file_count: Number of files matched the Input Path or Pattern field.
result.metadata.success_count: Number of files successfully encrypted.
result.metadata.failure_count: The number of files failed to be encrypted.
result.metadata.skip_count: Number of files skipped to be processed due to previous error or due to overwrite flag.
result.files.source_file: The source file path.
result.files.target_file: The target file path.
result.files.status: The status of the operation on the specific file. Possible values (Encrypted | Not encrypted).
result.files.message: The error message.
result.errors: List of generic or unexpected errors.

Code Block

title	Successful Encryption Example
collapse	true

{
  "exit_code": 0,
  "status_description": "Task executed successfully",
  "invocation": {
    "version": "1.0.0",
    "extension": "ue-gnupg",
    "fields": {
          ...
    }
  },
  "result": {
    "errors": [],
    "metadata": {
      "metadata": {
        "count": 2,
        "input_file_count": 3,
        "success_count": 1,
        "failure_count": 1,
        "skip_count": 1
      },
      "files": [
        {
          "source_file": "/source_directory/gpg_test1.txt",
          "target_file": "/target_directory/pgp_test1.txt.asc",
          "status": "Encrypted",
          "message": null
        },
        {
          "source_file": "/source_directory/gpg_test2.txt",
          "target_file": "/target_directory/pgp_test2.txt.asc",
          "status": "Encrypted",
          "message": null
        }
      ]
    }
  }
}

Code Block

title	Failed Execution
collapse	true

{
  "exit_code": 100,
  "status_description": "Execution failed: At least one file processing failed.",
  "invocation": {
    "version": "1.0.0",
    "extension": "ue-gnupg",
    "fields": {
          ...
    }
  },
  "result": {
    "metadata": {
        "count": 3,
        "input_file_count": 4
        "success_count": 1,
        "failure_count": 2,
        "skip_count": 1
    },
    "files": [
        {
            "source_file": "/source_directory/pgp_test1.txt",
            "target_file": "/target_directory/pgp_test1.txt.pgp",
            "status": "Encrypted",
            "message": null
        },
        {
            "source_file": "/source_directory/pgp_test2.txt",
            "target_file": "/source_directory/pgp_test2.txt.pgp",
            "status": "Not encrypted",
            "message": "invalid recipient, not found:dummy.pub"
        },
        {
            "source_file": "/source_directory/pgp_test3.txt",
            "target_file": "/source_directory/pgp_test3.txt.pgp",
            "status": "Not encrypted",
            "message": "invalid recipient, not found:dummy.pub"
        }
    ]
  }

Code Block

title	Generic Failed Execution
collapse	true

{
  "exit_code": 1,
  "status_description": "Execution Failed: ...",
  "invocation": {
    "version": "1.0.0",
    "extension": "ue-gnupg",
    "fields": {
          ...
    }
  }
  "result": {
    "errors": [
      "Execution Failed: ..."
    ]
  }
}

STDOUT

Display in STDOUT all GPG tool verbose information when ‘UE_GNUPG_VERBOSE_OUTPUT’ environment variable is true/True.

Code Block

title	STDOUT Example
collapse	true

gpg --status-fd 2 --no-tty --no-verbose --fixed-list-mode --batch --with-colons --homedir C:\DATA\gpg --list-config --with-colons
gpg --status-fd 2 --no-tty --no-verbose --fixed-list-mode --batch --with-colons --homedir C:\DATA\gpg --encrypt --recipient robot_rsa --yes --output C:\DATA\windev76\UAGSrv\ue-gnupg-demo\test_rsa.txt.gpg --trust-model always
[GNUPG:] KEY_CONSIDERED 70BE8B3FBFCBC5638B6715EEFD9C1F2E818BD452 0
[GNUPG:] KEY_CONSIDERED 70BE8B3FBFCBC5638B6715EEFD9C1F2E818BD452 0
[GNUPG:] BEGIN_ENCRYPTION 2 9
[GNUPG:] END_ENCRYPTION

...

Encrypt a single file or multiple files given a file pattern. Optionally sign the encrypted file(s). Public key for encryption and Private key for signing, are retrieved from a UDMG server, though fields ‘UDMG Key Name' and 'UDMG Private Key For Signing' respectively.

Configuration examples

Image Modified

Encrypt and sign a single file, using keys stored on a UDMG server.

Retrieve the single file "finance_report.csv", and encrypt it, using PGP key that exists on a UDMG server. After the encryption is completed, sign the encrypted file. PGP Keys will temporarily be stored on the local GPG, and removed as soon the task instance is completed. Allow the integration to overwrite any existing encrypted file with the same name.

Encrypt multiple files, using keys stored on a UDMG server.

Retrieve all matching files based on filename pattern "finance_2*.csv", and encrypt them, using a PGP key that exists on the default keyring of the local GPG. The task instance will fail if no matching files are found. It will stop its execution on the first encryption error, and will skip to encrypt a file if there is an existing one with the same name encrypted.

Action Output

Info
Action Output is the same as described in Action Encrypt With Local Keystore 647528454.

Anchor

	Decrypt With Local Keystore
	Decrypt With Local Keystore

...

Decrypt a single file or multiple files given a file pattern. Optionally verify the signature of a signed and encrypted file. Private key for decryption is retrieved from local GPG keystore, through field 'Local Key'.

Configuration examples

Image Modified

Decrypt single file using private key stored in local GPG keystore and verify the signature.

Retrieve single file and decrypt it, using a PGP key that exists on the local GPG keystore. After the decryption is completed, verify the file has been signed by ‘admin.finance@example.com'. The task instance overwrite any file named ‘finance_report' and delete the original decrypted file 'finance_report.gpg’.

Decrypt multiple files using private key stored in local GPG keystore and verify the signature.

Retrieve all matching files based on filename pattern "finance_2*.gpg", and decrypt them, using a PGP key that exists on the local GPG keystore. After the decryption is completed, verify for each file that has a signature of email 'admin.finance@example.com'. Using a GPG option, ignore any MDC error produced during decryption. The task instance will stop its execution either when no matching files are found, or on the first decryption or verification error.

Action Output

Output Type

Description

Example

EXTENSION

The extension output provides the following information:

exit_code, status_description: General info regarding the task execution.
result.metadata.count: Number of files that have been decrypted. Skipped files are not counted here.
result.metadata.input_file_count: Number of files matched the Input Path or Pattern field.
result.metadata.success_count: Number of files successfully decrypted.
result.metadata.failure_count: The number of files failed to be decrypted.
result.metadata.skip_count: Number of files skipped to be processed due to previous error or due to overwrite flag.
result.files.source_file: The source file path.
result.files.target_file: The target file path.
result.files.status: The status of the operation on the specific file. Possible values (Decrypted | Not decrypted).
result.files.message: The error message.
result.errors: List of generic or unexpected errors.

Code Block

title	Successful Execution
collapse	true

{
  "exit_code": 0,
  "status_description": "Task executed successfully",
  "invocation": {
    "version": "1.0.0",
    "extension": "ue-gnupg",
    "fields": {
          ...
    }
  },
  "result": {
    "errors": [],
    "metadata": {
      "metadata": {
        "count": 2,
        "input_file_count": 3,
        "success_count": 1,
        "failure_count": 1,
        "skip_count": 1
      },
      "files": [
        {
          "source_file": "/source_directory/gpg_test1.txt.gpg",
          "target_file": "/target_directory/pgp_test1.txt",
          "status": "Decrypted",
          "message": " decryption ok"
        },
        {
          "source_file": "/source_directory/gpg_test2.txt.gpg",
          "target_file": "/target_directory/pgp_test2.txt",
          "status": "Not decrypted",
          "message": "not found:my_key private key"
        }
      ]
    }
  }
}

Code Block

title	Failed Execution
collapse	true

{
  "exit_code": 100,
  "status_description": "Execution failed: At least one file processing failed.",
  "invocation": {
    "version": "1.0.0",
    "extension": "ue-gnupg",
    "fields": {
            ...
    }
  },
  "result": {
    "metadata": {
        "count": 3,
        "input_file_count": 4,
        "success_count": 1,
        "failure_count": 2,
        "skip_count": 1
    },
    "files": [
        {
            "source_file": "/source_directory/pgp_test1.txt.pgp",
            "target_file": "/target_directory/pgp_test1.txt",
            "status": "Decrypted",
            "message": null
        },
        {
            "source_file": "/source_directory/pgp_test2.txt.pgp",
            "target_file": "/target_directory/pgp_test2.txt",
            "status": "Not decrypted",
            "message": " not valid data"
        },
        {
            "source_file": "/source_directory/pgp_test3.txt.pgp",
            "target_file": null,
            "target_file": "/target_directory/pgp_test3.txt",
            "status": "Not decrypted",
            "message": " not valid data"
        },
    ]
  }
}

Code Block

title	Generic Failed Execution
collapse	true

{
  "exit_code": 1,
  "status_description": "Execution Failed: ...",
  "invocation": {
    "version": "1.0.0",
    "extension": "ue-gnupg",
    "fields": {
          ...
    }
  }
  "result": {
    "errors": [
      "Execution Failed: ..."
    ]
  }
}

STDOUT

Display in STDOUT all GPG tool verbose information when ‘UE_GNUPG_VERBOSE_OUTPUT’ environment variable is true/True.

Code Block

title	STDOUT Example
collapse	true

gpg --status-fd 2 --no-tty --no-verbose --fixed-list-mode --batch --with-colons 
--homedir C:\DATA\gpg --list-config --with-colons
gpg --pinentry-mode loopback --status-fd 2 --no-tty --no-verbose --fixed-list-mode 
--batch --with-colons --homedir C:\DATA\gpg --passphrase-fd 0 --decrypt --yes 
--output C:\DATA\windev76\UAGSrv\ue-gnupg-demo\test_rsa.txt --trust-model always
[GNUPG:] ENC_TO BCA783824F1E76CD 1 0
[GNUPG:] KEY_CONSIDERED 70BE8B3FBFCBC5638B6715EEFD9C1F2E818BD452 0
gpg: encrypted with rsa3072 key, ID BCA783824F1E76CD, created 2024-02-08
      "robot_rsa <robot.rsa@ueqa.com>"
[GNUPG:] KEY_CONSIDERED 70BE8B3FBFCBC5638B6715EEFD9C1F2E818BD452 0
[GNUPG:] KEY_CONSIDERED 70BE8B3FBFCBC5638B6715EEFD9C1F2E818BD452 0
[GNUPG:] DECRYPTION_KEY 67FB5708B59E2CBB646A5DCFBCA783824F1E76CD 70BE8B3FBFCBC5638B6715EEFD9C1F2E818BD452 -
[GNUPG:] BEGIN_DECRYPTION
[GNUPG:] DECRYPTION_INFO 2 9 0
[GNUPG:] PLAINTEXT 62 1707406246 test_rsa.txt
[GNUPG:] PLAINTEXT_LENGTH 6790
[GNUPG:] DECRYPTION_OKAY
[GNUPG:] GOODMDC
[GNUPG:] END_DECRYPTION

...

Decrypt a single file or multiple files given a file pattern. Optionally verify the signature of a signed and encrypted file. Private key for decryption is retrieved from a UDMG server, through field 'UDMG Key Name'.

Configuration examples

Decrypt a single file using a private key stored on a UDMG server.

Retrieve a single file based and decrypt it, using a PGP key that exists on a UDMG server. The task instance will stop its execution on the first decryption or verification error and will overwrite any existing decrypted file with the same name.

Decrypt multiple files with private key stored on UDMG server and verify their signature.

Retrieve all matching files based on filename pattern "finance_2*.csv", and decrypt them, using a PGP key that exists on a UDMG server. After the decryption is completed, verify for each file that has a signature of email 'admin.finance@example.com'. Using a GPG option, ignore any MDC error produced during decryption. The task instance will stop its execution on the first decryption or verification error.

Action Output

Info
Action Output is the same as described in Action Decrypt With Local Keystore.

Input Fields

Name

Type

Description

Version Information

Action

Choice

The action performed upon the task execution.

Encrypt With Local Keystore
Encrypt With UDMG Keystore
Decrypt With Local Keystore
Decrypt With UDMG Keystore

Introduced in 1.0.0

Input Path or Pattern

Text

Source directory containing the file(s) to encrypt/decrypt. When file path pattern is provided, all matched files will be used.

Introduced in 1.0.0

Output Path

Text

Directory to store the encrypted/decrypted files.

Introduced in 1.0.0

File Extension

Choice

The file extension that will be appended in the encrypted files. Choose the extension that will be used for the encrypted files. Available options:

.gpg (GNUPG)
.pgp (PGP)
.asc (ASCII armored)

Visible when Action = [ Encrypt With Local Keystore | Encrypt With UDMG Keystore]

Introduced in 1.0.0

Local Key

Credentials

The UID or Email that will be used for the selected action. Should reflect to an existing GPG key in the local GPG keystore or the keyring that is specified in the Keyring field.

The Credentials should be populated as follows:

The UID or Email of the local key as “Runtime User”.
Private key’s passphrase, (onlywhen Action = Decrypt With Local Keystore) as "Passphrase".

Visible and required when Action = [ Encrypt With Local Keystore | Decrypt With Local Keystore]).

Introduced in 1.0.0

UDMG Server

Text

UDMG Server API endpoint.

Example: http://<udmg_url>:<port>/api

Visible and required when Action = [ Encrypt With UDMG Keystore | Decrypt With UDMG Keystore ].

Introduced in 1.0.0

UDMG Credentials

Credentials

Credentials for UDMG Server.

User as "Runtime User".
User Password as "Runtime Password".

Visible and required when Action = [ Encrypt With UDMG Keystore | Decrypt With UDMG Keystore].

Introduced in 1.0.0

UDMG Key Name

Dynamic Choice

A list of all the available PGP keys retrieved from UDMG Server, one of which should be used for the selected action.

When Action = Encrypt With UDMG Keystore, the available Public Keys are listed. When Action = Decrypt With UDMG Keystore, the available Private Keys are listed.

Visible and required when Action = [ Encrypt With UDMG Keystore | Decrypt With UDMG Keystore ].

Introduced in 1.0.0

Sign

Checkbox

After encryption is completed, optionally sign the encrypted file with the sender’s private key.

Default setting is unchecked.

Introduced in 1.0.0

Private Key For Signing

Credentials

Credentials representing the Private key used to sign the encrypted file(s).

The UID or Email of the local key as “Runtime User”.
Private key’s passphrase as "Passphrase".

Visible and required when Sign is checked.

Introduced in 1.0.0

Verify File Signed By

Text

The email of the person/key who has signed the file that was decrypted.

When a signed file is decrypted, an implicit signature verification is performed. Populating this field, will force the task instance to perform an additional validation that the signature is from the expected person.

Info
Decryption is irrelevant with the signature verification. This means that a file can be successfully decrypted, however the signature verification might fail. In this case, a corresponding message is present in the Extension Output result.file.message field for the specific file.

Visible when Action=[Decrypt With Local Keystore | Decrypt With UDMG Keystore].

Introduced in 1.0.0

UDMG Private Key For Signing

Dynamic Choice

A list of all the available PGP Private keys retrieved from UDMG Server, one of which should be used for signing the encrypted files.

Visible and required when Sign is checked.

Introduced in 1.0.0

Overwrite Output File

Checkbox

When is checked, the output file(s) will overwrite the existing ones, if any.

Default setting is checked.

Introduced in 1.0.0

Delete After Encryption

Checkbox

When is checked, delete the input file(s) after encryption.

Visible when Action=[Encrypt With Local Keystore | Encrypt With UDMG Keystore].

Default setting is not checked.

Introduced in 1.0.0

Delete After Decryption

Checkbox

When is checked, delete the input file(s) after decryption.

Visible when Action= [Decrypt With Local Keystore | Decrypt With UDMG Keystore].

Default setting is not checked.

Introduced in 1.0.0

Fail On No Input Files

Checkbox

When selected, fails when no matching input files are found.

Default setting is not checked.

Introduced in 1.0.0

Fail On First Error

Checkbox

When is checked, fails on the first error that might occur during encryption/decryption and task instance fails with Exit Code 101.

Default setting is not checked.

Introduced in 1.0.0

Trust Keys

Checkbox

When is checked, skip key validation and assume that used keys are always fully trusted.

This option can be used with caution for imported keys.

Default setting is not checked.

Introduced in 1.0.0

GPG Home

Text

Home directory for the GnuGP tool. This is the location where default and/or custom keyrings can be stored.

Refer to the official GnuPG documentation for more details on the GnuPG Home Directory option.

Users are advised to use a custom GPG Home when Action = [Encrypt With UDMG Keystore | Decrypt With UDMG Keystore].

Introduced in 1.0.0

GPG Path

Text

The file path to the gpg executable.

Should be populated when gpg executable is not included in the PATH environment variable.

Introduced in 1.0.0

Keyring File

Text

Points to a keyring file. Use this field when other than the default GPG Keyring stored under GPG Home Directory is used. Populate the field according to the following cases:

When field is the absolute path to a keyring file is provided, it will be respected.
When field is the keyring filename, it will be expected to be found under the GPG Home.

Please refer to official documentation for more details on the keyring usage, depending on the Linux or Windows OS.

Visible when Action = [Encrypt With Local Keystore | Decrypt With Local Keystore].

Extra Arguments

Large Text

A space separated list of extra arguments that can be provided to the GPG command line tool.

A usage example can be found under Action 'Decrypt With Local Keystore 647528454'.

Introduced in 1.0.0

Exit Codes

Text

Enter exit codes or ranges of exit codes and treat them as Success or Fail exit codes.

This is the default field in the main tab of each Universal Template. Refer to Integration Modifications 647528454.

Default value is: 0

Default Task Field

...

Example can be found under Action 'Encrypt With Local Keystore 647528454'.

Exit Codes

Exit Code	Status	Status Description	Meaning
0	Success	Task executed successfully.	Successful Execution
1	Failed	Execution Failed: <Error Description>.	Generic Error identifying a failed execution.
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	Failed	Execution failed: At least one file processing failed.	At least one file has failed to be encrypted/decrypted, or signature has failed to be verified according to the given Email.
101	Failed	Execution failed: All file processing failed.	All files have been failed to be encrypted/decrypted.

...

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 647528454.

Configure Universal Task

...

Versions Compared

Old Version 6

New Version 7

Key

Disclaimer

Version Information

Overview

Key Features

Software Requirements

Configuration examples

Action Output

Configuration examples

Action Output

Configuration examples

Action Output

Configuration examples

Action Output

Input Fields

Exit Codes

Configure Universal Task

Page Comparison

Versions Compared

Old Version 6

New Version 7

Key

Disclaimer

Version Information

Overview

Key Features

Software Requirements

Configuration examples

Action Output

Configuration examples

Action Output

Configuration examples

Action Output

Configuration examples

Action Output

Input Fields

Exit Codes

Configure Universal Task