UAC Utility: GnuPG
- 1 Disclaimer
- 2 Version Information
- 3 Overview
- 4 Supported Actions
- 5 Input Fields
- 6 Environment Variables
- 7 Exit Codes
- 8 STDOUT and STDERR
- 9 GnuPG - How To
- 10 How To
- 11 Document References
- 12 Changelog
- 12.1 ue-gnupg-2.0.0 (2025-12-19)
- 12.1.1 Deprecations and Breaking Changes
- 12.1.2 Enhancements
- 12.1.3 Fixes
- 12.2 ue-gnupg-1.1.1 (2025-08-21)
- 12.2.1 Fixes
- 12.3 ue-gnupg-1.1.0 (2024-11-07)
- 12.3.1 Enhancements
- 12.4 ue-gnupg-1.0.1 (2024-08-08)
- 12.4.1 Fixes
- 12.5 ue-gnupg-1.0.0 (2024-06-06)
- 12.1 ue-gnupg-2.0.0 (2025-12-19)
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 | Status |
|---|---|---|---|
GnuPG | ue-gnupg | 2 (Current 2.0.0) | Fixes and new features are introduced. Compatibility starts from UAC/UAG 7.6.0.0 onwards. |
Version 2.0.0 is a major release and introduces breaking changes that might affect some customers depending on their setup. Administrators are strongly advised to refer to Changelog for more information on the changes introduced in this release.
Refer to Changelog 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, signing, and verification 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. |
Support for UDMG versions 2 and 3
As of release 2.0.0, UDMG versions 2 and 3 are supported. The versions can be used for the actions related to encryption and decryption using UDMG keystore. The key difference is that UDMG version 3 requires a domain to be specified. Additionally, for UDMG version 3 the passphrase of the private key needs to be specified using UDMG or UAC credentials, unlike UDMG version 2 where the passphrase already comes embedded in the private key, so users do not need to provide it separately.
Software Requirements
This integration requires a Universal Agent and a Python runtime to execute the Universal Task.
Area | Details |
|---|---|
Python Version | Requires Python 3.11, tested with Agent bundled python distribution |
Universal Agent |
Only Agents that are Under Support are supported. |
Universal Controller | Universal Controller Version >= 7.6.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. |
Supported Actions
Action: Encrypt With Local Keystore
Encrypt a single file or multiple files given a file pattern. Optionally sign the encrypted file(s). The Public key for encryption and Private Key for signing are retrieved from the local GnuPG keystore, through the ‘Local Key' and 'Private Key For Signing' fields, respectively.
Configuration examples
Use Case: Encrypt and sign a single file, using keys stored in a keyring file on the local GPG.
Retrieve the single file "finance_2024_may.csv" and encrypt it in ASCII format, using a PGP key stored in a local GPG keyring file in the /home/.gnupg directory. After encryption is completed, sign the encrypted file. Allow the integration to overwrite any existing encrypted file with the same name.
Use Case: Encrypt and sign multiple files matching a pattern, using keys stored in the default keyring of the local GPG.
Retrieve all matching files based on the filename pattern "finance_2*.csv" and encrypt them in ASCII format, using a PGP key stored in the default keyring of the local GPG. After encryption is completed, sign the encrypted files. The task instance will fail on the first encryption error or if no matching files are found.
Action Output
Output Type | Description | Example |
|---|---|---|
EXTENSION | The extension output provides the following information:
| Successful Encryption Example{
"exit_code": 0,
"status_description": "Task executed successfully",
"invocation": {
"version": "2.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
}
]
}
}
}Failed Execution{
"exit_code": 100,
"status_description": "Execution failed: At least one file processing failed.",
"invocation": {
"version": "2.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"
}
]
}Generic Failed Execution{
"exit_code": 1,
"status_description": "Execution Failed: ...",
"invocation": {
"version": "2.0.0",
"extension": "ue-gnupg",
"fields": {
...
}
}
"result": {
"errors": [
"Execution Failed: ..."
]
}
} |
Action: Encrypt With UDMG Keystore
Encrypt a single file or multiple files given a file pattern. Optionally sign the encrypted file(s). The Public key for encryption and Private key for signing are retrieved from a UDMG server, through the ‘UDMG Key Name' and 'UDMG Private Key For Signing' fields, respectively.
Configuration examples
Use Case: Encrypt and sign a single file, using keys stored on a UDMG server.
Retrieve the single file "finance_report.csv" and encrypt it, using a PGP key stored on a UDMG version 3 server. After encryption is completed, sign the encrypted file. PGP keys will be temporarily stored on the local GPG, then removed as soon the task instance completes. Allow the integration to overwrite any existing encrypted file with the same name. Use SSL verification and the environment variable UE_SSL_CERT_FILE to specify the path to the CA bundle.
Use Case: 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 is stored on a UDMG version 2 server. The integration will skip encryption of any existing encrypted file with the same name. The task instance will fail on the first encryption error or if no matching files are found. SSL verification is disabled.
Action Output
Action Output is the same as described in Action Encrypt With Local Keystore.
Action: 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 the local GPG keystore, through the 'Local Key' field.
Configuration examples
Use Case: Decrypt a single file using a Private Key stored in the local GPG keystore and verify the signature.
Retrieve a single file and decrypt it, using a PGP key stored in the local GPG keystore. After decryption is completed, verify that the file has been signed by ‘admin.finance@example.com'. Allow the integration to overwrite any existing decrypted file with the same name. The task instance will delete the original decrypted file 'finance_report.gpg’.
Use Case: Decrypt multiple files using a Private Key stored in the 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 stored in the local GPG keystore. After decryption is completed, verify that each file has been signed by 'admin.finance@example.com'. Using a GPG option, ignore any MDC error produced during decryption. The task instance will fail on the first decryption or verification error, or if no matching files are found.
Action Output
Output Type | Description | Example |
|---|---|---|
EXTENSION | The extension output provides the following information:
| Successful Execution{
"exit_code": 0,
"status_description": "Task executed successfully",
"invocation": {
"version": "2.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"
}
]
}
}
}Failed Execution{
"exit_code": 100,
"status_description": "Execution failed: At least one file processing failed.",
"invocation": {
"version": "2.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"
},
]
}
}
Generic Failed Execution{
"exit_code": 1,
"status_description": "Execution Failed: ...",
"invocation": {
"version": "2.0.0",
"extension": "ue-gnupg",
"fields": {
...
}
}
"result": {
"errors": [
"Execution Failed: ..."
]
}
} |
Action: Decrypt With UDMG 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 a UDMG server, through the 'UDMG Key Name' field.
Configuration examples
Use Case: Decrypt a single file using a private key stored on a UDMG server.
Retrieve a single file 'finance_report.gpg' and decrypt it, using a PGP key stored on a UDMG version 3 server. Allow the integration to overwrite any existing decrypted file with the same name. The task instance will fail on the first decryption or verification error. SSL verification is enabled.
Use Case: 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 version 2 server. After the decryption is completed, verify that each file has been signed by 'admin.finance@example.com'. Using a GPG option, ignore any MDC error produced during decryption. The task instance will fail on the first decryption or verification error. SSL verification is enabled.
Action Output
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.
| 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:
Visible when Action is "Encrypt With Local Keystore" or "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 specified as follows:
Visible and required when Action is "Encrypt With Local Keystore" or "Decrypt With Local Keystore". | Introduced in 1.0.0 |
UDMG Server | Text | UDMG Server API endpoint. Example: http://<udmg_url>:<port>/api for using HTTP communication. Example: https://<udmg_url>:<port>/api for using HTTPS communication. Visible and required when Action is "Encrypt With UDMG Keystore or "Decrypt With UDMG Keystore". | Introduced in 1.0.0 |
Enable SSL Verification | Checkbox | Enable/disable SSL certificate verification of the UDMG instance. A path to a certificate bundle may be specified using the UE_SSL_CERT_FILE environment variable. Default setting is checked. Visible and required when Action is "Encrypt With Local Keystore" or "Encrypt With UDMG Keystore". | Introduced in 2.0.0 |
Domain | Text | The UDMG domain to be used mandatory for UDMG version 3. | Introduced in 2.0.0 |
UDMG Credentials | Credentials | Credentials for UDMG Server.
Visible and required when Action is "Encrypt With UDMG Keystore or "Decrypt With UDMG Keystore". | Introduced in 1.0.0 |
UDMG Key Name | Dynamic Choice | A list of all the available PGP keys retrieved from the UDMG Server, one of which should be used for the selected action. When Action is "Encrypt With UDMG Keystore", the available Public Keys are listed. When Action is "Decrypt With UDMG Keystore", the available Private Keys are listed. Visible and required when Action is "Encrypt With UDMG Keystore or "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).
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. Decryption is irrelevant to the signature verification. This means that a file can be successfully decrypted, but 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 is "Decrypt With Local Keystore" or "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 the 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 |
UDMG Private Key Passphrase Source | Choice | Determines the source from where to get passphrase for private key. The following options are available.
Visible when Sign is checked or Action is "Decrypt With UDMG Keystore". | Introduced in 2.0.0 |
Passphrase as UAC Credential | Credential | Get the passphrase from a UAC credentials record. The UAC credentials can be defined as follows.
Visible and required when UDMG Private Key Passphrase Source is "UAC (Only in case of UDMG V3 Onwards)". | Introduced in 2.0.0 |
Passphrase as UDMG Credential | Dynamic Choice | Get the passphrase from a UDMG credentials record. The UDMG credentials can be defined as follows.
Visible and required when UDMG Private Key Passphrase Source is "UDMG (Only in case of UDMG V3 Onwards)". | Introduced in 2.0.0 |
Overwrite Output File | Checkbox | When 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 checked, delete the input file(s) after encryption. Visible when Action is "Encrypt With Local Keystore" or "Encrypt With UDMG Keystore". Default setting is unchecked. | Introduced in 1.0.0 |
Delete After Decryption | Checkbox | When checked, delete the input file(s) after decryption. Visible when Action is "Decrypt With Local Keystore" or "Decrypt With UDMG Keystore". Default setting is unchecked. | Introduced in 1.0.0 |
Fail On No Input Files | Checkbox | When selected, fails when no matching input files are found. Default setting is unchecked. | Introduced in 1.0.0 |
Fail On First Error | Checkbox | When checked, fails on the first error that might occur during encryption/decryption. Task instance fails with Exit Code 101. Default setting is unchecked. | Introduced in 1.0.0 |
Trust Keys | Checkbox | When checked, skip key validation and assume that used keys are always fully trusted. This option should be used with caution for imported keys. Default setting is unchecked. | 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. |