Skip to main content

PGP Encryption

Use PGP encryption to encrypt and decrypt files that are exported or imported into Varicent Incentives storage.

Prerequisites

Each model in your Incentives application can have only one set of PGP keys.

A set of PGP keys includes your public PGP key and a public PGP key that is provided by Varicent. For example, if you have Production, QA, and Development environments, then you can have a unique set of PGP keys for each environment. Alternatively, you can use the same set for all three environments. However, a single environment cannot use more than one pair of PGP keys. Varicent provides one public PGP key per environment or one public PGP key for all environments.

If you require PGP encryption, then you must provide Varicent with your public PGP key that has the name parameter set to outbound and a strength of 2048 bits.

Scheduling PGP encryption and decryption

PGP encryption and decryption tasks are run via Scheduler as a System Tool.

For both PGP actions, you must specify the parameters for the input and output file paths.

  1. Open Scheduler and select the process folder that you want to add a task to.

  2. Click the Add icon.

  3. From the Type menu, select System Tool.

  4. You can set the schedule for the task by completing the following steps:

    1. Select either the day of the month or the day of the week when you want the task to run.

    2. Select the minute and hour that you want the task to run on.

    3. Select the month that you want the task to run in.

  5. From the Available system tools menu, select either PGPEncrypt or PGPDecrypt.

  6. In the Input file path field, type the location of the file that you want to encrypt or decrypt in the following format: <folder>/<file name>.

    For example, Publication/payee.pdf.

    Note

    The file path fields are case-sensitive.

  7. In the Output file path, type the location that you want the file to be placed after it is encrypted or decrypted. It must also be in the following format: <folder>/<file name>.

    Tip

    Use Data, Document, Image, Publication, or Script as the base path for SFTP files.

  8. If you want to use wildcard pattern matching, follow these steps:

    1. In the Input file path field, type the location of the files that you want to encrypt or decrypt in the following format: <folder>/<file name pattern>.

      For example, Data/payee*.pdf. This file path matches any files in the Data folder that start with payee and end with .pdf.

    2. In the Output file path, type the location that you want the file to be placed after it is encrypted or decrypted. It must also be in the following format: <folder>/<file name pattern> or <folder>.

      For example, Data/*.gpg. New files have .gpg appended to the name and written to the Data folder.

  9. Click Create.

PGP encryption automation

Automate PGP encryption and decryption.

Automation requires external tools to ensure that no conflicts occur when outputs are being created and the expected file names are present for consumption in downstream processes.

Example

This example simulates a basic workflow for a PGP encrypted file that needs to be imported into Incentives and use PGP encryption to export a published file.

Prerequisites

The following external tools are required for this workflow:

remove_file.py

This external tool deletes a specified file if it exists.

remove_timestamp.py

This external tool looks for and deletes the most recent timestamp for the specified file prefix.

Sample workflow

  • SFTP - The file import.csv.pgp is moved to the /root/Data folder.

  • Scheduler - The external tool, remove_file.py /root/Data/import.csv removes any decrypted files from the previous Scheduler run.

  • Scheduler - The system tool, PGPDecrypt, with the /root/Data/import.csv.pgp and /root/Data/import.csv file paths, decrypts the newly uploaded import file.

  • Scheduler - The necessary tasks with the decrypted import file are run.

  • Scheduler - The report-timestamp.pdf file is published.

  • Scheduler - The external tool, remove_file.py /root/Publication/report.pdf cleans up the file from the last Scheduler run.

  • Scheduler - The external tool, remove_file.py /root/Publication/report.pdf.pgp cleans up the file from the last Scheduler run.

  • Scheduler - The external tool, remove_timestamp.py /root/Pubication/report.pdf removes the timestamp from the most recent published report file.

  • Scheduler - The system tool, PGPEncrypt, with the /root/Publication/report.pdf and /root/Publication/report.pdf.pgp file paths, encrypts the published report file.

  • SFTP - The file report.pdf.pgp can now be copied out of the Incentives application.

Rules for wildcard pattern matching

When you use wildcard pattern matching, there are rules for both input and output file paths.

Input file path

Valid file paths

You can use multiple wildcards in the same input file path by using *. For example, these file paths are valid:

  • path/to/*_2018_*

  • path/to/*.*

You can use prefixes and suffixes in input file paths. For example, these file paths are valid:

  • path/to/prefix*

  • path/to/prefix*suffix

  • path/to/*suffix

Invalid file paths

Caution

File paths must not contain ?

You cannot use wildcard pattern matching in folder names. For example, path/*/file.txt is invalid.

You cannot use wildcard pattern matching in directory names. For example, the valid file path path/to/* cannot find this file path: path/to/innerfolder/sample_file.txt.

Scheduler rules

If a wildcard pattern matches no files, the scheduled task succeeds.

If a wildcard pattern matches multiple files, but is unable to encrypt or decrypt a file, the process continues by trying to process other files that match the pattern. The scheduled task fails.

Output file path

You can use directories with output file paths only if the input file path contains a wildcard. For example, path/subdir is valid if the folder exists and can be written to.

Note

The output file name will be the same as the input file name.

You can use wildcard pattern matching in an output file path only if the input file path also contains a wildcard.

If there is a wildcard in the input, the output file path must also have a wildcard.

Valid file paths

You can use only one wildcard symbol in an output file path. For example, these file paths are valid:

  • path/output/*

  • path/to/prefix_*.txt

You can use prefixes and suffixes in output file names. For example, these file paths are valid:

  • path/output/2018_11_28_* results in the file name 2018_11_28_ prefix

  • path/output/*.gpg maps the input files sample_file.txt and sample_file.test.txt to path/output/sample_file.txt.gpg and path/output/sample_file.test.txt.gpg.

Invalid file paths

Caution

File paths must not contain ?

You can use only one wildcard symbol in an output file path. For example, these file paths are invalid:

  • path/to/*_2018_*

  • path/to/*.*

You cannot use wildcard pattern matching in folder names. For example, path/*/result.gpg.

Encryption examples

Here are some examples of encryption behavior with and without wildcard pattern matching.

You have these files:

  • Data/sample_file

  • Data/sample_file.txt

  • Data/sample_file.2018.txt

  • Data/other_FILE

PGPEncrypt Data/sample_file Data/output/sample_file.gpg creates a single encrypted file at Data/output/sample_file.gpg. If the Data/output directory does not exist, the encryption fails.

PGPEncrypt Data/sample*.* creates two encrypted files (if the data/output directory does not exist, the encryption fails):

  • Data/sample_file.txt becomes Data/encrypted/sample_file.txt

  • Data/sample_file.2018.txt becomes Data/encrypted/sample_file.2018.txt

PGPEncrypt Data/* Data/encrypted/prefix_*.gpg creates these encrypted files (if the data/output directory does not exist, the encryption fails):

  • Data/sample_file becomes Data/prefix_sample_file.gpg

  • Data/sample_file.txt becomes Data/prefix_sample_file.txt.gpg

  • Data/sample_file.2018.txt becomes Data/prefix_sample_file.2018.txt.gpg

  • Data/other_FILE becomes Data/prefix_other_FILE.gpg

PGPEncrypt Data/*file* Data/encrypted_*.gpg creates these encrypted files:

  • Data/sample_file becomes Data/encrypted_sample_file.gpg

  • Data/sample_file.txt becomes Data/encrypted_sample_file.txt.gpg

  • Data/sample_file.2018.txt becomes Data/encrypted_sample_file.2018.txt.gpg

Decryption examples

Here are some examples of decryption behavior with and without wildcard pattern matching.

You have these files:

  • Data/file1.txt.gpg

  • Data/file2.txt.gpg

  • Data/file3.csv.gpg

  • Data/file4.gpg

  • Data/results.2018

  • Data/decrypted/

  • Data/output/

PGPDecrypt Data/file1.txt.gpg Data/output/sample_file.txt creates a single decrypted file at Data/output/sample_file.txt. If the Data/output directory does not exist, the decryption fails.

PGPDecrypt Data/*.txt* Data/decrypted/* creates two decrypted files:

  • Data/decrypted/file1.txt

  • Data/decrypted/file2.txt

PGPDecrypt Data/*.csv.gpg Data/decrypted/ where the output path does not have a wildcard creates a decrypted file at Data/decrypted/file3.csv.gpg.

PGPDecrypt Data/*.gpg Data/decrypted/Processed_* creates these decrypted files:

  • Data/decrypted/Processed_file1.txt

  • Data/decrypted/Processed_file2.txt

  • Data/decrypted/Processed_file3.csv

  • Data/decrypted/Processed_file4

Troubleshooting PGP encryption or decryption

Troubleshooting PGP encryption or decryption

Troubleshoot common reasons for PGP encryption or decryption task failure.

Input or output file path contains a space

PGP encryption or decryption fail can fail if your input or output path contains a space.

Symptoms

Encryption or decryption task fails.

Causes

Input or output file path contains spaces.

Resolving the problem

Surround the path with quotation marks. For example, “Data/2018 Quarter 3 results.xlsx”.

Input or output file path does not match case

PGP encryption or decryption fail can fail if your input or output path is not case-sensitive.

Symptoms

Encryption or decryption task fails.

Causes

Input or output file path does not match case.

Resolving the problem

Check your file paths. File paths are case-sensitive. Update your file paths so they match exactly.

Wildcard pattern matching on input file path only

PGP encryption or decryption fail can fail if your input file path contains wildcard pattern matching, but your output file path does not. A previous release supported wildcard pattern matching on input file paths without a wildcard in the output file path. If you are using this deprecated definition, you must replace the System Tool in Scheduler with the new definition.

Symptoms

Encryption or decryption task fails.

Causes

The input fail path contains a wildcard, but the output file path does not.

Resolving the problem

Create an encryption or decryption task to replace the old one. Ensure that the output file path uses wildcard pattern matching.

Table 87. Examples of valid and invalid file paths

Type

Validation

Input file paths

Output file path

Encryption

Invalid

Publication/Folder/*.pdf

Publication/Folder/name.gpg

Encryption

Valid

Publication/Folder/*.pdf

Publication/Folder/*.gpg

Decryption

Invalid

PGPDecrypt Publication/*.zip.gpg

Publication/name.zip

Decryption

Valid

PGPDecrypt Publication/*.zip.gpg

Publication/*



Cannot write to directory

PGP encryption or decryption fail can fail if you do not have permission to write to the directory specified.

Symptoms

Encryption or decryption task fails.

Causes

User does not have permission to write to the directory.

Resolving the problem

Modify the directory permissions through an SFTP connection so you can write to the directory.