...
| Panel | ||||
|---|---|---|---|---|
|
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 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
This integration requires a Universal Agent and a Python runtime to execute the Universal Task.
...
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.4.0.0.
Compatible with Universal Agent for Linux and version >= 7.4.0.0.
Only Agents that are Under Support are supported.
...
Universal Controller
...
Universal Controller Version >= 7.4.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). 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
...
...
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 | ||||
|---|---|---|---|---|
| ||||
{
"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 | ||||
|---|---|---|---|---|
| ||||
{
"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 | ||||
|---|---|---|---|---|
| ||||
{
"exit_code": 1,
"status_description": "Execution Failed: ...",
"invocation": {
"version": "1.0.0",
"extension": "ue-gnupg",
"fields": {
...
}
}
"result": {
"errors": [
"Execution Failed: ..."
]
}
} |
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
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
|
Action: Encrypt With UDMG Keystore
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
...
...
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. |
...
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 local GPG keystore, through field 'Local Key'.
Configuration examples
...
...
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 | ||||
|---|---|---|---|---|
| ||||
{
"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 | ||||
|---|---|---|---|---|
| ||||
{
"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 | ||||
|---|---|---|---|---|
| ||||
{
"exit_code": 1,
"status_description": "Execution Failed: ...",
"invocation": {
"version": "1.0.0",
"extension": "ue-gnupg",
"fields": {
...
}
}
"result": {
"errors": [
"Execution Failed: ..."
]
}
} |
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
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 |
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 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”.
...
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'.
...
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.
Default value is: 0
...
Default Task Field
Environment Variables
Variable: UE_GNUPG_VERBOSE_OUTPUT
This environment variable can be used to enable the verbosity of the underlying GnuPG tool. Since the GnuPG logging can be comprehensive, it is suggested to configure this variable for troubleshooting purposes, or when this is requested by the Stonebranch Customer Support.
Accepted values are: True/False or environment variable not set.
Default value: not set.
Example can be found under Action 'Encrypt With Local Keystore'.
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.
STDOUT and STDERR
STDOUT of this integration provides verbose logging of the executed GPG command line. STDERR provides additional information to the user, the detail of it is tuned by Log Level Task Definition field.
| Info |
|---|
Backward compatibility is not guaranteed for the content of STDOUT/STDERR and can be changed in future versions without notice |
GnuPG - How To
The following sections describe sample scenarios of managing GPG keys with GnuPG cli tool.
...
Generate GPG Key Pair - default way (RSA Algorithm)
...
gpg --generate-key...
At this step, you will be prompted to input a passphrase for the private key.
The public and private keys are generated and stored in binary format.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
(venv) vagrant@ubuntu-bionic:~$ gpg --generate-key
gpg (GnuPG) 2.2.4; Copyright (C) 2017 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Note: Use "gpg --full-generate-key" for a full featured key generation dialog.
GnuPG needs to construct a user ID to identify your key.
Real name: ue_gpg
Email address: ue_gpg@example.com
You selected this USER-ID:
"ue_gpg<ue_gpg@example.com>"
Change (N)ame, (E)mail, or (O)kay/(Q)uit? O
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: key 6108ADC464ED7963 marked as ultimately trusted
gpg: directory '/home/vagrant/.gnupg/openpgp-revocs.d' created
gpg: revocation certificate stored as '/home/vagrant/.gnupg/openpgp-revocs.d/CF610B70872C3981A7F890D06108ADC464ED7963.rev'
public and secret key created and signed.
pub rsa3072 2024-02-06 [SC] [expires: 2026-02-05]
CF610B70872C3981A7F890D06108ADC464ED7963
uid ue_gpg<ue_gpg@example.com>
sub rsa3072 2024-02-06 [E] [expires: 2026-02-05] |
...
Generate GPG keypair - choose encryption algorithm
...
gpg --full-generate-key...
At this step, you will be prompted to input a passphrase for the private key.
Choose a different encryption algorithm, other than the default RSA. In this example, ‘ElGamal’ is chosen.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
venv) vagrant@ubuntu-bionic:~$ gpg --full-generate-key
gpg (GnuPG) 2.2.4; Copyright (C) 2017 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Please select what kind of key you want:
(1) RSA and RSA (default)
(2) DSA and Elgamal
(3) DSA (sign only)
(4) RSA (sign only)
Your selection? 2
DSA keys may be between 1024 and 3072 bits long.
What keysize do you want? (2048) 1024
Requested keysize is 1024 bits
Please specify how long the key should be valid.
0 = key does not expire
<n> = key expires in n days
<n>w = key expires in n weeks
<n>m = key expires in n months
<n>y = key expires in n years
Key is valid for? (0) 0
Key does not expire at all
Is this correct? (y/N) y
GnuPG needs to construct a user ID to identify your key.
Real name: ue_gpg_elg
Email address: ue_gpg_elg@example.com
Comment: This key pair uses DSA and ElGamal Algorithm
You selected this USER-ID:
"ue_gpg_elg(This key pair uses DSA and ElGamal Algorithm) <ue_gpg_elg@example.com>"
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: key D4471D13493DA3C8 marked as ultimately trusted
gpg: revocation certificate stored as '/home/vagrant/.gnupg/openpgp-revocs.d/AFD9027733280F78ED5A74CAD4471D13493DA3C8.rev'
public and secret key created and signed.
pub dsa1024 2024-02-06 [SC]
AFD9027733280F78ED5A74CAD4471D13493DA3C8
uid ue_gpg_elg(This key pair uses DSA and ElGamal Algorithm) <ue_gpg_elg@example.com>
sub elg1024 2024-02-06 [E]
|
...
gpg --export --armor <uid> > my_secret.pub| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
(venv) vagrant@ubuntu-bionic:~$ gpg --export -a ue_gpg > ./ue_gpg_pub.asc
(venv) vagrant@ubuntu-bionic:~$ cat ./ue_gpg_pub.asc
|
...
gpg --export-secret-keys -a [uid] > my_secret.key...
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
(venv) vagrant@ubuntu-bionic:~$ gpg --export-secret-keys -a ue_gpg> ./ue_gpg_pkey.asc
(venv) vagrant@ubuntu-bionic:~$ cat./ue_gpg_pkey.asc
|
...
List Keys
...
gpg --list-keysThe above command will prompt only the public keys. To get prompted with the private keys, execute the command:
gpg --list-secret-keys
...
gpg --homedir <dir> --list-keys
To list keys stored on a custom keyring file:
gpg --keyring <absolute path to keyring file> --no-default-keyring --list-keys
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
(venv) vagrant@ubuntu-bionic:~$ gpg --list-keys
gpg: checking the trustdb
gpg: marginals needed: 3 completes needed: 1 trust model: pgp
gpg: depth: 0 valid: 2 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 2u
gpg: next trustdb check due at 2026-02-05
/home/vagrant/.gnupg/pubring.kbx
--------------------------------
pub rsa3072 2024-02-06 [SC] [expires: 2026-02-05]
CF610B70872C3981A7F890D06108ADC464ED7963
uid [ultimate] ue_gpg<ue_gpg@example.com>
sub rsa3072 2024-02-06 [E] [expires: 2026-02-05]
pub dsa1024 2024-02-06 [SC]
AFD9027733280F78ED5A74CAD4471D13493DA3C8
uid [ultimate] ue_gpg_elg (This key pair uses DSA and ElGamal Algorithm) <ue_gpg_elg@example.com>
sub elg1024 2024-02-06 [E] |
...
Import GPG Public Keys
...
gpg --import <pub key file> [--homedir <>]| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
(venv) vagrant@ubuntu-bionic:~$ gpg --import ue_gpg.pub
gpg: key FD9C1F2E818BD452: public key "ue_gpg<ue_gpg@example.com>" imported
gpg: Total number processed: 1
gpg: imported: 1
(venv) vagrant@ubuntu-bionic:~$ |
...
Import GPG Private Keys
...
gpg --import <pkey file> [--homedir <>]At this point you will be prompted to enter the key passphrase.
| Info |
|---|
Private keys should be carefully imported into a system. In order to use a private key properly, you might need to update its trust method. To do so, execute the interactive command: gpg --trust . Choose the appropriate options as per your needs, and then run gpg --save to save the changes. |
...
| language | bash |
|---|---|
| title | Import Private Key |
| collapse | true |
...
| Panel | ||||
|---|---|---|---|---|
|
Disclaimer
Your use of this download is governed by Stonebranch’s Terms of Use, which are available here.
Version Information
| Template Name | Extension Name | Version | Status |
|---|---|---|---|
HTTP Download | ue-http-download | 1.0.0 | Features and Bug Fixes are introduced |
Refer to Changelog for version history information.
Overview
Downloading content from an HTTP server is a common operation in various scenarios, including File Transfer, Data Synchronization, Web Scrapping, Data Analysisand more. This integration provides the capability to download content over HTTP protocol and store it on the Universal Agent's File System for later processing.
Key Features
| Feature | Description |
|---|---|
Download content from the web | Store the downloaded content in file on the Universal Agent's file system. |
Support multiple authentication types | Most common authentication mechanisms are supported, including Token, API Key and Basic. |
Progress Bar | Review the downloaded content’s progress (only for HTTP responses that provide the header Content-Length.) |
Checksum verification | Optionally the checksum of the downloaded content can be verified. |
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 Python 3.7.6 and Python 3.11.6. |
Universal Agent Compatibility |
|
Universal Controller Compatibility | Universal Controller Version >= 7.4.0.0. |
Supported Actions
Action: Download Content
This integration is responsible for downloading content from web and store it in a file on the Universal Agent’s file system.
Configuration examples
The following examples demonstrate a few real life scenarios.
| Info |
|---|
The task configuration combinations are not restrictive to the examples. |
No authentication - File extension automatically identified - Verify Checksum
|
|
Download a binary file and verify its checksum. The name of the downloaded file is determined by a best-effort algorithm. File is stored in Runtime Directory path. |
|
Token authentication - Custom file extension
|
|
| Download the contents of a resource. Custom Output Filename is provided, thus respected during download. File is stored in Runtime Directory path. | result JSON element of the Extension Output from the Task Instance execution. |
Action Output
Output Type | Description | Examples | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| EXTENSION | The extension output provides the following information:
|
|
Input Fields
| Name | Type | Description | Version Information |
|---|---|---|---|
| Action | Choice | The action performed upon the task execution.
| Introduced in 1.0.0 |
| URL | Large Text | The endpoint which results to a downloadable content. | Introduced in 1.0.0 |
Authorization Type | Choice | The authorization type to be used for communicating with the foreign API. The following options are available.
No authorization details are sent with the request.
Basic authentication involves sending a username and password with the request.
The request is authorized through the use of an API key.
The request is authorized through the use of a known access token. This option is used typically if the access token is retrieved by former task execution. | Introduced in 1.0.0 |
| Credentials | Credentials | Credentials for different Authorization Types. The Credentials definition should be populated as follows. For Authorization Type=Basic:
For Authorization Type=Token:
For Authorization Type=API Key:
| Introduced in 1.0.0 |
Add Authorization Data To | Choice | Specifies where to include the API Key in the request. The following options are available:
Required when Authorization Type is "API Key". | Introduced in 1.0.0 |
| SSL Options | Checkbox | Enables additional SSL options. Default setting is unchecked. | Introduced in 1.0.0 |
SSL Certificate Verification | Checkbox | Enables certificate verification. Certificate verification is auto-enabled in case field "CA Bundle Path" field is populated. Default setting is checked. | Introduced in 1.0.0 |
CA Bundle Path | Text | Path and file name of the Certificate Authority bundle to use in certificate verification. The file should be in PEM format. Visible when SSL Certificate Verification is checked. | Introduced in 1.0.0 |
| Headers | Array | The list of HTTP Headers key/value pairs to be sent with the request. | Introduced in 1.0.0 |
| Output Filename | Text | The name of the file where the content will be stored. The full file path is also supported. If not provided, a best-effort algorithm is used to determine the name under which the downloaded content will be stored. If absolute file path is not provided, the downloaded content is stored in the Runtime Directory. | Introduced in 1.0.0 |
| Timeout | Integer | The time (in seconds) that the request will wait for the server to send data before closing the connection. If Timeout is not filled, the request will wait (hang) until the connection is closed. | Introduced in 1.0.0 |
Checksum Algorithm | Choice | The algorithm that will be used in order to validate the checksum of the downloaded content. The following options are available:
| Introduced in 1.0.0 |
| Checksum | Text | The checksum provided from the source host, for the downloaded content. Visible when Checksum Algorithm = [MD5 | SHA-1 | SHA-256]. | Introduced in 1.0.0 |
Exit Codes
| Anchor | ||||
|---|---|---|---|---|
|
| Exit Code | Status | Status Description | Meaning |
|---|---|---|---|
0 | Success | “SUCCESS: Task executed successfully.“ | Successful Execution |
| 1 | Failure | “Execution Failed: <<Error Description>>” | Generic Error identifying a failed execution. |
| 2 | Failure | “Authentication Error: Account cannot be authenticated.“ | Bad credentials |
| 3 | Failure | “Authorization Error: Account is not authorized to perform the requested action.“ | Insufficient permissions |
| 20 | Failure | “Data Validation Error: <<Error Description>>” | An input fields cannot be validated. |
STDOUT and STDERR
STDOUT and STDERR provide additional information to the user.
| Note |
|---|
Backward compatibility is not guaranteed for the content of STDOUT/STDERR and can be changed in future versions without notice. |
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
...
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
i. Success/Failure exit codes need to be respected.
...
ii. 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.
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. |
...
...
User documentation of GnuPG command line tool.
Changelog
| Anchor |
|---|
...
|
...
|
Changelog
ue-http-
...
download-1.0.0 (2024-06-06)
Initial
...
Version