PGPENCRYPT        Encrypt a file using PGP

<< Click to Display Table of Contents >>

Navigation:  Robo-FTP User's Guide > Script Programming > Script Commands > All Script Commands >

PGPENCRYPT        Encrypt a file using PGP

Syntax:

PGPENCRYPT

[ source file ] [ target file ] [  options ]

Arguments:

[ source file ]

A variable or string defining the file name of the file to encrypt with PGP. Wildcards are not permitted in [ source file ] or [ target file ].

 

[ target file ]

A variable or string defining the file name of the newly encrypted file; if the file existed, it will be overwritten. The target file must not be the same as the source file.

Options:

/armor

Select this option to ASCII armor the [ target file ].

 

/cipher=xx

Specify the encryption cipher. The possible values are: AES, AES192, AES256, IDEA, CAST5, Blowfish, Twofish, and 3DES

 

/compat

Creates an output file compatible with older implementations of PGP but cannot create a file over 2GB in size. This option may not be combined with the /cipher option.

 

/pw=xx

This option is used together with the /sign option. The purpose of this option is to specify the passphrase associated with the private key that will be used to digitally sign the output file. This option is not required for keys created in the Configurator using the "save passphrase" feature.

 

/compress=true|false

This option can be used to control PGP compression. The default option is true so this would usually be used in the form of /compress=false to disable compression.

 

/nostatus

Suppresses the display of the progress bar.

 

/textmode

Set a flag indicating file is text allowing platforms with differing line endings to convert upon decryption.

 

/encryptfor=xx

This option may be used to specify one or more public keys with which to encrypt the file. The option accepts an argument containing an unambiguous keyspec of a public key.  A keyspec is a a full or partial match of a given PGP key's user name, email, or key id fields, as displayed in the Configurator's PGP Keys page. You may encrypt with multiple public keys by using /encryptfor option more than once, or you may separate a sequence of keyspecs with the pipe symbol '|'. See below for more information about the keyspec format.

 

/header=xx

Add an arbitrary header to the top of an ASCII-armored PGP file. To specify multiple headers, use this argument multiple times, as in the following example: /header="MD5: 378fa020da87104f88ed86cddea9605a" /header="CRC32: DEADBEEF".

 

/sign

Select this option to digitally sign the output file using the default private key. If the default private key was not created in the Configurator using the "save passphrase" feature you will need to also use the /pw=xx option to specify the private key passphrase.

 

/signwith=xx

This option may be used to specify one or more private keys with which to sign the file. The option accepts an argument containing an unambiguous keyspec of a private key.  A keyspec is a a full or partial match of a given PGP key's user name, email, or key id fields, as displayed in the Configurator's PGP Keys page. You may sign with multiple secret keys by using /signwith option more than once, or you may separate a sequence of keyspecs with the pipe symbol '|'. Specifying multiple signing keys can only be done using those keys for which the password is already saved in the Configurator. See below for more information about the keyspec format.

 

/symmetricpw=xx

Password-protect the file with symmetric encryption instead of using a key.

Deprecated:

 

The following options still work but are deprecated.

 

/signuser=xx

This option is used together with the /sign option. The purpose of this option is to specify the signer's private key. This option is required if you have more than one private key stored in the Configurator and you wish to sign a file with a private key other than the default private key. The value passed must be at least a partial match to one, and only one, private key as listed in the Key Name or Key ID column on the Manage Keys form.

 

/user=xx

The /user option is required to specify the public PGP key of the recipient of the encrypted file. The value passed must match one, and only one, public key as listed in either the Key Name or Key ID column on the Manage Keys form. To encrypt a file with multiple public keys use the pipe character "|" to separate each key identifier string or simply repeat this option once for each public key.

 

 

 

This script command encrypts and/or digitally signs a file using PGP. Files may be decrypted and/or verified using the Robo-FTP PGPDECRYPT script command or any other PGP or GPG encryption application.

 

To encrypt a file, you must first import the public key of the recipient into Robo-FTP. Keys are imported by way of the PGPIMPORT script command or by using the Import Key functionality in the Robo-FTP Configurator. Imported keys are displayed in the Configurator on the Configure PGP menu

 

To sign a file, you must first create or import a pgp key pair. Keys are imported by way of the PGPIMPORT script command or by using the Import Key functionality in the Robo-FTP Configurator. They can be created using the Create Key functionality in the Robo-FTP Configurator. You must then export the public key from the key pair and send it to your intended recipient. They will use the public key to verify your signature.

 

The /encryptfor and /signwith options are used to specify the PGP keys used for encrypting and signing. The arguments to these options must be either an unambiguous keyspec or else a list of unambiguous keyspecs separated by the pipe symbol (|). A keyspec (key specification) is a full or partial match to one of the three values that are displayed in the Key Name column on the Configurator's PGP Keys table or to the Key ID column on the same table. The Key Name column is a composite value formatted as: name (comment) <email>. If matching against a partial Key ID, at least 8 characters of the Key ID must be provided. If a keyspec matches against multiple PGP keys, Robo-FTP will be unable to determine which key was intended. Such a keyspec is ambiguous, and Robo-FTP will issue the following error "*Key specification ambiguous, more than one key matches. [1283]".

 

Consider the following PGP key table:

pgp_keyspec

 

The following 6 keyspecs can be used to uniquely identify each of these keys:

Alex

barkman

Monty

Trebek

58FD0A69

mhall@gmail

   

Use the /armor option if you wish the resulting file to be in ASCII armored format.

 

Use the /cipher option to select the cipher used by Robo-FTP to encrypt a file. The default CAST5 cipher should be fine for most situations but some providers may require (or exclude) a particular cipher. The available ciphers are: AES, AES192, AES256, IDEA, CAST5, Blowfish, Twofish, and 3DES. The /compat option may not be used with /cipher because /compat always uses the IDEA cipher.

 

Use the /sign option if you wish the resulting file to be digitally signed with the default private key stored in the Configurator. If you have more than one private key stored in the Configurator and you wish to sign a file with a key other than the default private key, you must specify which key you wish to use with the /signwith option.

 

Use the /textmode option if you wish the resulting file to be a text mode format.

 

Use the /compress=false option if you wish to disable compression of the output. This is mostly used when only signing a file so that it will remain readable without first calling PGPDECRYPT on it to extract the original file and verify the signature.

 

When signing a file, you must specify your passphrase either within the command itself using the /pw option or by previously saving it in the Robo-FTP Configurator.

 

Important

When you use the Configurator to create new PGP keys you may optionally choose to save the passphrase. If you choose this option, the password is saved in an encrypted format in the Windows registry along with Robo-FTP's other settings. Later, when you use these keys for encryption or decryption, the passphrase will not appear in the console window nor will it be written to any log file. If you choose not to save the passphrase (or if you use externally generated PGP keys) then you will probably need to specify the passphrase in clear-text in a script file. Therefore, saving the passphrase when you create the key is the most secure option.

 

It is typical for encrypted files to have an extension of .pgp, .gpg, or .asc (if ascii armored). In most of the examples below, we add one of these extensions at the end of the original file to create the name of the encrypted version of the file. We recommend that you adopt these conventions as well.

 

Original File Name: "datafile.txt"

Encrypted File Name: "datafile.txt.pgp"

 

For ASCII armored files (see below):

 

Original File Name: "datafile.txt"

Encrypted File Name: "datafile.txt.asc"

 

In the example below, a file is encrypted using a public key identified by a partial match on the Key Name column.

 

PGPENCRYPT "datafile.txt" "datafile.txt.pgp" /encryptfor="Richard Tracy"

 

In the following example, a file is encrypted using a public key identified by an exact match on the Key ID column.

 

PGPENCRYPT "datafile.txt" "datafile.txt.pgp" /encryptfor="A7743F3F33AC30A7"

 

Two public keys are used for encryption when the /encryptfor option is specified twice or when the pipe character is used to separate the key identification string. Both lines below produce the same result.

 

PGPENCRYPT "datafile.txt" "datafile.txt.pgp" /encryptfor="Richard Tracy" /encryptfor="Mike Hammer"

PGPENCRYPT "datafile.txt" "datafile.txt.pgp" /encryptfor="Richard Tracy|Mike Hammer"

 

The following example encrypts a file and specifies the output format to be ASCII armored. (The .asc extension is typically used for these types of files.)

 

PGPENCRYPT "datafile.txt" "datafile.txt.asc" /encryptfor="Richard Tracy" /armor

 

The following example encrypts a file for Richard Tracy and digitally signs it using a specified private key (John Doe).

 

PGPENCRYPT "datafile.txt" "datafile.txt.pgp" /encryptfor="Richard" /signwith="John Doe" /pw="John Doe's passphrase"

 

Hint: If the recipient is unable to decrypt the file ask them for the Key ID of the public key that they expected you to use for encryption. The Key ID must match the value shown on the PGP Keys menu in the Configurator. Some PGP software only displays an 8 character Key ID so in those cases you'll compare with the last 8 digits of the value shown in the Configurator. For a more precise comparison you can right-click the grid row and choose "Show Key Fingerprint" from the pop-up context menu.

 

Note: When the TMPNAME command is active, the output [ target file ] created by this command will have a different name until the encryption process is successfully completed.

 

 

Related command(s): PGPDECRYPT, PGPIMPORT, ZIP, TMPNAME

See also: Robo-FTP and PGP Cryptography, Configure PGP Menu, Compatibility with older versions of PGP