Cryptography
- Sign
Declaration
<AMSIGN INPUTFILE="text" OUTPUTFILE="text" SUBFOLDERS="Yes/No" OVERWRITE="Yes/No" ISNEWER="Yes/No" PUBKEYRINGPATH="text" SECKEYRINGPATH="text"><SIGNATURE KEYID="text" PASSWORD="text" /></AMSIGN>
Overview
Digitally signs a file using the specified private keys. The files can be signed by multiple keys.
Practical usage
Protects files from being tampered with by digitally signing them. Digital signing uses a key pair and encrypts the message with the private key to produce a signature file. You can later use the Verify activity to validate and decrypt the signature.
Parameters
General
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Source | Text | Yes | (Empty) |
|
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 |
|
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. |
| Keyring file(s) - Public | Text | Yes | (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 | (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 you click Select recipients. 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. |
Signature
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Sign type | Text (options) | Yes | Non-detached | SIGNTYPE="clear_text" | Specifies the digital signature. The available options are:
|
| Hash algorithm | Text (options) | Yes | Auto |
|
Specifies the hash algorithm. The available options are:
|
| Signer(s) - Email or Name | Text | Yes | (Empty) |
|
Specifies
the signer's name or email address used to locate the private
key. You can select existing signatures (populated using values entered in the
Public keyring file and
Secret keyring file parameters)
by selecting Select signer(s). To manually enter an email address or name, select an empty box and enter the email address or unique name. To remove a recipient, click X. NOTE: At least one signature is required. Therefore, you need to specify one email address
or name from the keyring along with its keyring passphrase. If there is no password associated with the email
address or name in the keyring, then you can leave the Password
parameter empty. Additionally, if no name or email address
is used to identify the key, make sure to empty the Email
or Name field of any contents. |
| Signer(s) - Password | Text | Yes | (Empty) | PASSWORD="encrypted" | Specifies
the password to add to the private key. You can select existing signatures
(populated using the Public Keyring
File and Secret Keyring
File parameters) by selecting Select signer(s). To manually enter a password, select an empty box and enter it. To remove a signer, click X. NOTE: At least one signature is required. Therefore, one email address
or name from the keyring along with its keyring passphrase needs
to be entered. If there is no password associated with the email
address or name in the keyring, then you can leave the Password
parameter empty. Additionally, if no name or email address
is used to identify the key, make sure to empty the Email
or Name field of any contents. |
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 is 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. |
| 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. |
| Text compatibility mode | Yes/No | No | Yes | TEXTLEGACYMODE="NO" | If selected (default), this parameter enables legacy text mode. |
| 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. |
| Compression algorithm | Text (options) | No | ZIP |
|
Specifies the compression algorithm to use to encrypt the files. The available options are:
|
| 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" | Omits decrypting files matching the masks specified. You can use filenames or wildcard masks. You can specify multiple entries 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)%" | Only decrypts files if the source is newer than the specified date/time. 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)%" | Only decrypts files if the source is older than the specified date/time. 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 will be 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 should be 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 used to track if a file is 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. |
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 decrypt information for applications that run under that specific user identity. User-level RSA key containers can be useful 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 makes use of 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 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 table below 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 that will be 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 will remain empty. |
| theDataset.ExecutionDate | Date | The date and time the dataset is created and populated |
| 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.Signer | Text | The name and email address of the signer. |
| theDataset.Source | Text | The path and file name of the source folder and file. |
| theDataset.SQLQuery | Text | The SQL Query that was 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. |
Example
- 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.
Description
The following sample task signs and then saves the file:
<AMCRYPTOGRAPHY ACTIVITY="sign" INPUTFILE="C:\test\file_to_encrypt.txt" OUTPUTFILE="C:\test\signed.txt" RESULTDATASET="Signed" PUBKEYRINGPATH="C:\test\PGPKeyManager\BobKeyring.pkr" SECKEYRINGPATH="C:\test\PGPKeyManager\BobKeyring.skr" SIGNTYPE="detached" COMPRESSIONALGO="zip"><SIGNER KEYID="Bob <bob@mail.com>" PASSWORD="AM5kGQo5F8NZyV/9lneQTlDfqb+ORnc8FLzOR089KGzxXE=aME" /></AMCRYPTOGRAPHY>