Cryptography - Encrypt

Declaration

<AMCRYPTOGRAPHY ACTIVITY="encrypt" SUBFOLDERS="yes/no" KEEPFOLDERSTRUCT="yes/no" OVERWRITE="yes/no" ISNEWER="yes/no" ONLYIFEXIST="yes/no" OVERWRITEREADONLY="yes/no" OVERWRITEHIDDEN="yes/no" ARCHIVETURNOFF="yes/no" MATCHCASE="yes/no" EXCLUDE="text" RE="yes/no" INPUTFILE="text" OUTPUTFILE="text" RESULTDATASET="text" PASSPHRASE="text (encrypted)" USEOLDPACKETS="YES/NO" SELFEXTRACT="YES/NO" TAR="YES/NO" ARMOR="YES/NO" COMPRESSIONALGO="text (options)" APPENDEXTENSION="text" />

Related Topics    

Overview

Encrypts one or more files using the specified encryption method and algorithm. This action supports both symmetric (passphrase) and asymmetric (public/private key) encryption types.

NOTE: PGP (Pretty Good Privacy) is a popular program used to encrypt and decrypt email over the Internet. You can also use it to send an encrypted digital signature that allows the receiver verify the sender's identity. Automate Desktop includes the OpenPGP engine, which is based on PGP as originally developed. OpenPGP is installed on the system during Automate Desktop installation.

Practical usage

Used for security purposes to encrypt any type of file. Ideal for keeping sensitive and confidential information private.

Parameters

General

Property Type Required Default Markup Description
Source Text Yes (Empty)
  • INPUTFILE="c:\source\file.txt"
  • INPUTFILE="c:\source\*.txt"
 The path and file name of the files to encrypt. This can be a fully qualified path and file name (preferred) or a single file (requires use of the File System - Change folder activity). You can use wildcard characters (for example, * or ?) to specify all files matching a certain mask. You can specify multiple files and file masks by separating each entry with a pipe (|). For example, c:\temp\*.txt|c:\backup\*.bak. See File Masks & Wildcards for more information.
NOTE: Files with invalid paths are ignored at runtime.
Destination Text Yes User
  • OUTPUTFILE="c:\destfile.txt"
  • OUTPUTFILE="c:\dest\
 The destination folder and (optional) file name to place the newly encrypted files. Folders that do not exist are automatically created at runtime.
Create and populate decrypt dataset Text No (Empty) RESULTDATASET="theResult" The name of the dataset to create and populate with results of this activity. See Datasets for more information.

Encrypt

Property Type Required Default Markup Description
Encryption type Text (options) Yes Passphrase

  • ENCRYPTTYPE="openpgppassphrase"

  • ENCRYPTTYPE="openpgpkey"

  • ENCRYPTTYPE="pgppassphrase"

  • ENCRYPTTYPE="openpgpkey"

  • ENCRYPTTYPE="passphrase"

  • ENCRYPTTYPE="key"

 Specifies the type of encryption to use. The available options are:
  • OpenPGP passphrase (Default) - Requires a particular passphrase to verify and encrypt the specified files.
  • OpenPGP public key - Encryption is performed using OpenPGP public key and can only be encrypted with the corresponding public key.
  • PGP passphrase - Requires a particular OpenPGP passphrase to encrypt.
  • PGP public key - Uses a system which binds the public keys to an email address. Requires the associated PGP public key to encrypt.
  • Passphrase - Requires a particular OpenPGP passphrase to encrypt.
  • Public key -An asymmetric form of encryption that relies on a cryptographically generated public/private key pair. Encryption is performed with the public key and can only be decrypted with the corresponding private key.
NOTE: You must place an encryption key in a key container to ensure proper encryption. You must create a key container outside of Automate Desktop.
Symmetric algorithm Text (Options) Yes, if Encryption type set to OpenPGP passphrase, OpenPGP public key, PGP Passphrase or Passphrase CAST5

  • ENCRYPTALGO="rijndael"

  • ENCRYPTALGO="des"

  • ENCRYPTALGO="rc2"

  • ENCRYPTALGO="tripledes"

 The encryption algorithm to use. This parameter is active only if Encryption type parameter is set to OpenPGP passphrase, OpenPGP public key, PGP Passphrase or Passphrase.

Available encryption algorithm options for OpenPGP passphrase, OpenPGP public key or PGP Passphrase are:

  • Plain text
  • IDEA (PGP Only)
  • TripleDES
  • CAST5 (Default)
  • BLOWFISH
  • AES128
  • AES192
  • AES256
  • TWOFISH256

Available encryption algorithm options for Passphrase are:

  • Rijndae (Default)
  • DES
  • RC2
  • TripleDES
Passphrase Text Yes, if Encryption type set to OpenPGP passphrase, PGP passphrase or Passphrase (Empty) PASSWORD="encrypted" The passphrase to use in order to encrypt the files. This parameter is available only if the Encryption type parameter is set to OpenPGP passphrase, PGP passphrase, or Passphrase.
Keyring file(s) - Public Text Yes, if Encryption type set to OpenPGP public key or PGP public key (Empty) PUBKEYRINGPATH="c:\foldername\file.pkr" Specifies the path and file name of the OpenPGP or PGP public keyring file (.pkr). Entering a valid public keyring file along with a matching secret keyring file populates the Recipient(s) section with the appropriate signature information when you click Select recipients. This parameter is available only if the Encryption type parameter is set to OpenPGP public key or PGP public key.
NOTE: Automate Desktop includes the OpenPGP engine which is installed on the system during Automate Desktop installation.  
Keyring file(s) - Secret Text Yes, if Encryption type set to PGP public key (Empty) SECKEYRINGPATH="c:\foldername\file.skr" Specifies the path and file name of the PGP secret keyring file (.skr). Entering a valid public keyring file along with a matching secret keyring file populates the Recipient(s) section with the appropriate signature information when pressing the Select recipients button. This parameter is available only if the Encryption type parameter is set to PGP public key.
NOTE: Automate Desktop includes the OpenPGP engine which is installed on the system during Automate Desktop installation.  
Recipient(s) - Email or Name Text No (Empty) RECPIENT KEYID=John@netauto.com Specifies the email address and/or unique name in which to bind the OpenPGP public key to. Select Select recipient(s) to populate this field with the recipient email and/or name. You can enter multiple names/email addresses by separating each entry with a semi-colon (;). This parameter is active only if the Encryption type parameter is set to OpenPGP public key.
Compress data before encryption Yes/No No Yes COMPRESS="YES" If selected, specifies that the files are initially compressed before encryption is performed. This parameter is active only if the Encryption type parameter is set to OpenPGP passphrase, PGP passphrase or PGP public key.
Key email Text Yes, if Encryption type set to PGP public key (Empty) EMAIL="john@netauto.com The email address used to identify the PGP public key. This parameter is available only if the Encryption type parameter is set to PGP public key.
Encrypt using Text (Options) Yes, if Encryption type is set to Public key Key Container
  • ENCRYPTUSING="KEYCONTAINER"
  • ENCRYPTUSING="KEYCFILE"
 Indicates the encryption procedure to be used to encrypt the specified files. This parameter is active only if the Encryption type parameter is set to Public key. The available options are:
  • Key container - A key container is used to encrypt the files.
  • Key file - A key file is used to encrypt the files. Click the Folder icon to navigate to the appropriate private key (.pri) file or enter the full path and file name of the private key file in the provided text box.
Key container name Yes/No Yes, if Decrypt using set to Key container (Empty) KEYCONTAINERNAME="Microsoft Enhanced Cryptographic Provider v1.0" Specifies the name of the key container to be used. Clicking the down arrow displays a list of cryptographic provider names to select from. This parameter is active only if the Encrypt using parameter is set to Key container.
NOTE: You must create a key container outside of Automate Desktop.
Key container level Text Options Yes, if Encrypt using set to Key container User
  • KEYCONTAINERLEVEL="user"
  • KEYCONTAINERLEVEL="machine"
 Specifies whether the new key container should be set to User-Level or Machine-Level. Microsoft Windows makes Machine-Level key containers available to all users, whereas a User-Level key container is available only to the user that created (or imported) the key container. The available options are:
  • User (Default) - User-level key container
  • Machine - Machine-level key container

This parameter is available only if the Encryption type parameter is set to Public key and the Decrypt using parameter is set to Key container name.
Public key path Text Yes, if Encrypt using parameter set to Key file (Empty) KEYCONTAINERNAME="C:\Temp\filename.pri" Specifies the path and file name of the public key file to be used. Click the Folder icon to navigate to the appropriate key file or enter the full path and file name of the key file in the provided text box. This parameter is active only if the Encrypt using parameter is set to Key file.

Advanced

Property Type Required Default Markup Description
Use new features (PGP > 6.5.x) Yes/No No Yes USENEWFEATURES="NO" If selected (default), newer PGP features introduced in 6.5.x are supported.
Use old packets (PGP 2.3.x, 6.5.x) Yes/No No Yes USEOLDPACKETS="YES" If selected, older PGP encryption algorithm is supported. Disabled by default.
Make TAR archive Yes/No No No TAR="YES" If selected, this parameter creates a TAR-formatted archive file of the encrypted files. Disabled by default.
Make self-extractable file Yes/No No No SELFEXTRACT="YES" If selected, this parameter creates an extractable version of the encrypted files. Selecting this parameter also adds .exe to the Append extension parameter.
Armor data (text output) Yes/No No No ARMOR="YES" If selected, causes PGP or OpenPGP to enable ASCII Armor output, a form of encoding binary data in a sequence of ASCII-printable characters. Binary to text encoding is necessary for transmission of data when the channel or the protocol only allows ASCII-printable characters, such as transporting through email channels. If you intend to use PGP primarily for email purposes, we suggest enabling this option. This parameter is active only if the Encryption type parameter is set to OpenPGP passphrase, PGP passphrase or PGP public key.
Compression algorithm Text (options) No ZIP

  • COMPRESSIONALGO="none"

  • COMPRESSIONALGO="zlib"

  • COMPRESSIONALGO="bzip2"

Specifies the compression algorithm to use to encrypt the files. The available options are:

  • None

  • ZIP

  • ZLib

  • BZip2
Append extension Text No (Empty) APPENDEXTENSION=".exe" Appends the specified extension to the encrypted files (for example, entering .enc renames file.zip to file.zipenc). When Make self-extractable file is selected, this parameter defaults to .exe to ensure the extractable can run.

File Options

Property Type Required Default Markup Description
Exclude mask Text No (Empty) EXCLUDE="*.txt" Causes this action to omit decrypting files matching the masks specified. You can use filenames or wildcard masks. Multiple entries may be specified by separating them with a pipe (|). For example: *.txt|*.bak.
Regular expression Yes/No No No RE="YES" If selected, specifies that a regular expression is used in the Exclude Mask field.
Only if newer than Date No (Empty) ISNEWERTHAN="%DateSerial(2007,10,12) + TimeSerial(00,00,00)%" Causes this action to only decrypt files if the source is newer than the date/time specified. If this parameter is left blank or not included, the date of the files is ignored (excluding Only if newer parameter).
Only if older than Date No (Empty) ISOLDERTHAN="%DateSerial(2007,10,12) + TimeSerial(00,00,00)%" Causes this action to only decrypt files if the source is older than the date/time specified. If this parameter is left blank or not included, the date of the files is ignored (excluding Only if newer parameter).
Overwrite if exists Yes/No No No OVERWRITE="YES" If selected, specifies that, if destination files already exist, they are overwritten. The default value is disabled.
Only if newer Yes/No No No ISNEWERTHAN="YES" If selected, indicates that only files that are newer than those in the destination folder overwrite existing files. Valid only if the Overwrite if Exists parameter is selected.
Only if exists in destination Yes/No No No ONLYIFEXIST="YES" If selected, specifies that only files that already exist in the destination will be decrypted from the source. All other files, regardless of whether they match the mask or other parameter settings are bypassed. Valid only if the Overwrite if Exists parameter is selected.
Overwrite read-only files Yes/No No No OVERWRITEREADONLY="YES" If selected, indicates that already existing files are overwritten even if the file in the destination is marked with the read-only attribute. By default, read only files are not overwritten. Valid only if the Overwrite if Exists parameter is selected.
Overwrite hidden files Yes/No No No OVERWRITEHIDDEN="YES" If selected, specifies that already existing files are overwritten even if the file in the destination is marked with the hidden attribute. By default, hidden files are not overwritten. Valid only if the Overwrite if Exists parameter is selected.
Include subfolders Yes/No No No SUBFOLDERS="YES" If selected, specifies that, if present, subfolders are searched for files matching the mask specified in the Source parameter. The default value is disabled.
Preserve folder structure Yes/No No Yes KEEPFOLDERSTRUCT="NO" If selected, specifies that subfolders found in the source folder are created in the destination folder, and source files are decrypted into their respective folders rather than directly into the root of the folder specified in the Destination parameter. Valid only if the Include subfolders parameter is selected.
Turn archive attribute off Yes/No No No ARCHIVETURNOFF="YES" If selected, the archive attribute of the source file is OFF. The Windows archive attribute is generally used to track whether a file backed up. By disabling the source file archive attribute, this indicates to many backup programs that the file is already backed up. This parameter is disabled by default.
Match case Yes/No No No MATCHCASE="YES" If selected, the properties set within this activity are case sensitive in relation to the file. This parameter is disabled by deafult.

File Attributes

Property Type Required Default Markup Description
Attributes Text Options No (Empty) ATTRFILTER="+R+A-H" (decrypt read-only & archive files but not hidden files) Causes the action to filter which files are decrypted based on the attribute settings of the source files. In visual mode, a group of controls are provided to assist in the selection of this parameter. In markup mode, a single text item must be specified that contains the attributes of the files you wish to decrypt. Available options are:
  • R—Read-only - Specifying +R causes files with this attribute turned on to be included, -R causes files with this attribute turned off to be included, not specifying the letter (default) causes this attribute to be ignored.
  • A—Archive - Specifying +A causes files with this attribute turned on to be included, -A causes files with this attribute turned off to be included, not specifying the letter (default) causes this attribute to be ignored.
  • S—System - Specifying +S causes files with this attribute turned on to be included, -S causes files with this attribute turned off to be included, not specifying the letter (default) causes this attribute to be ignored.
  • H—Hidden - Specifying +H causes files with this attribute turned on to be included, -H causes files with this attribute turned off to be included, not specifying the letter (default) causes this attribute to be ignored.
  • C—Compression - Specifying +C causes files with this attribute turned on to be included, -C causes files with this attribute turned off to be included, not specifying the letter (default) causes this attribute to be ignored.

Description

Error Causes

On Error

Additional notes

Comparing machine-level and user-level RSA key containers

User-level RSA key containers are stored with the Windows user profile and can be used to encrypt and encrypt information for applications that run under that specific user identity. User-level RSA key containers can be useful if you want to ensure that the RSA key information is removed when the Windows user profile is removed. However, because you must be logged in with the specific user account that uses the user-level RSA key container in order to encrypt or decrypt protected configuration sections, they are inconvenient to use.

Machine-level RSA key containers are available to all users that can log in to a computer, by default, and are the most useful as you can use them to encrypt or decrypt protected configuration sections while logged in with an administrator account. A machine-level RSA key container can be used to protect information for a single application, all the applications on a server, or a group of applications on a server that run under the same user identity. Although machine-level RSA key containers are available to all users, they can be secured with NTFS Access Control Lists (ACLs) so that only required users can access them.

Datasets

A dataset is a multiple column, multiple row container object where every column represents a particular variable, and each row corresponds to a given member of the dataset in question. This activity creates and populates a dataset containing specific fields (rows) in addition to the standard dataset fields. The following table describes these fields (assuming the dataset name assigned is theDataset):

Name Type Return value
theDataset.Cached True/False Returns TRUE if files are cached; otherwise, returns FALSE.
theDataset.ColumnNames Text A comma-delimited list of the column names in the dataset.
theDataset.CurrentRow Number The current row accessed in the dataset by an expression that does not contain a specific row index.
theDataset.Datasource Text The datasource used for the SQL Query, if applicable.
theDataset.Destination Text The path and file name of the destination file.
theDataset.Error Text A textual description of the error that occurred (if any). If no errors occurred during the decryption step, this dataset remains empty.
theDataset.ExecutionDate Date The date and time the dataset is created and populated
theDataset.Recipient Text The name or email address of the recipient.
theDataset.Result True/False Returns TRUE if result of activity is a success; otherwise, returns FALSE.
theDataset.RowsAffected Number The number of rows affected by an update.
theDataset.Source Text The path and file name of the source folder and file.
theDataset.SQLQuery Text The SQL Query used to generate this dataset. If a SQL Query is not used, this value is empty.
theDataset.TotalColumns Number The total number of rows in the dataset.
theDataset.TotalRows Number The total number of rows in the dataset.

Examples

NOTE:
  • Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
  • To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.

Example 1

The following sample task encrypts a file using passphrase encryption:

Copy 
<AMCRYPTOGRAPHY ACTIVITY="encrypt" SUBFOLDERS="yes" KEEPFOLDERSTRUCT="yes" OVERWRITE="yes" ISNEWER="yes" INPUTFILE="C:\SourceFolder\*.DOC" OUTPUTFILE="C:\DestinationFolder\encr*.doc" ENCRYPTTYPE="passphrase" PASSPHRASE="AM3hbDcFIyZYZs=aME" ATTRFILTER="+r" />

Example 2

This sample task encrypts a file using public key encryption.

Copy 
<AMCRYPTOGRAPHY ACTIVITY="encrypt" SUBFOLDERS="yes" KEEPFOLDERSTRUCT="yes" OVERWRITE="yes" ISNEWER="yes" INPUTFILE="C:\SourceFolder\*.DOC" OUTPUTFILE="C:\DestinationFolder\encr*.doc" ENCRYPTTYPE="key" KEYCONTAINERNAME="Microsoft Enhanced Cryptographic Provider v1.0" KEYCONTAINERLEVEL="user" ATTRFILTER="+r" />