CMSDECRYPT        Decrypt a CMS encrypted file

<< Click to Display Table of Contents >>

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

CMSDECRYPT        Decrypt a CMS encrypted file

Syntax:

CMSDECRYPT

[ source file ] [ target file ] [  options ]

Arguments:

[ source file ]

A variable or string defining the file name of a valid CMS (PKCS #7) file; this file may be encrypted, signed, or both encrypted and signed. Wildcards are not permitted in [ source file ] or [ target file ]

 

[ target file ]

A variable or string defining the file name of the outputted file; if the file exists, it will be overwritten. The target file may not be the same as the source file.

Options:

 

 

 

/signature=xx

required - a valid digital signature must exist  

optional - if there is a signature it must be valid (default)

ignore - signatures are ignored

 

/validatewith=xx

This option is used to specify the TLS certificate which should be used to validate the signature (if any) attached to the source file. Either the email address or common name of the certificate can be used, as displayed in the "View Certificate Details" dialog as found in the TLS Certificates page of the Configurator. Alternately, the email address and common name can be used together in the keyspec to look up the certificate, as follows: "My common name <[email protected]>".

 

 

This script command decrypts / verifies a CMS (PKCS #7) file that was previously encrypted / signed using the CMSENCRYPT command. To decrypt a file you must have already imported the PKCS#12 TLS certificate that corresponds to the X.509 TLS certificate that was used to encrypt the file. The certificate used for decryption will be contained in a .pfx (PKCS #12) file. Such certificates are imported by using the Import Certificate functionality in the Robo-FTP Configurator. To validate the signature of a file you must have already used the Robo-FTP Configurator to import the TLS certificate provided by the signer, which will be given as an X.509 certificate enclosed within a .cer or .pem file.

 

In the following example, the CMSDECRYPT command is used to decrypt and validate the signature of a file which was previously signed by "Fictional Company A" and encrypted in the CMS format for recipient "Fictional Company B". Because the /signature=required option is provided, if no signature is found inside the CMS file, an error will occur.  Note that in order for the recipient to successfully validate the signature in the file, Fictional Company A's X.509 TLS certificate (e.g. file "fictional_company_a.cer") must have been previously imported in the Configurator, as a TLS certificate ("for: encryption").  Additionally, for decryption to succeed, the recipient's PKCS #12 certificate (e.g. from file "fictional_company_b.pfx") must have been previously imported in the Configurator, as a TLS certificate ("for: decryption + signing"):

 

 CMSDECRYPT "plaintext.signed_and_encrypted.cms" "plaintext.txt"  /signature=required /validatewith="Fictional Company A"

 

In the following example, the same conditions apply, but with one exception. Since the /signature=required option has been changed to /signature=ignore, the file will be decrypted into the target file "plaintext.txt", regardless of the existence or validity of any enclosed signature in the source file:

 

 CMSDECRYPT "plaintext.signed_and_encrypted.cms" "plaintext.txt"  /signature=ignore

 

Return Values

These are the possible result codes returned by the CMSDECRYPT command:

 

$ERROR Constant Name

Code

Description

$ERROR_SUCCESS

0

No error occurred

$ERROR_FILE_OPEN_ERROR

1003

Unable to create the output specified by the [ target file ] argument

$ERROR_VAR_NOT_FOUND

1009

Script variable not set

$FILE_NOT_FOUND

1055

Unable to access the source specified by the [ source file ] argument

$ERROR_INVALID_ARGUMENT

1100

Invalid argument

$ERROR_CMS_DECRYPTION_FAILED

1348

PGP decryption operation failed or canceled

$ERROR_CMS_KEY_DOES_NOT_EXIST

1280

Private decryption key not imported or unavailable to current user

$ERROR_CMS_SIGNATURE_MODIFIED

1357

Signature not validated; the file contents have changed since it was signed or the signer's public key was not imported or is unavailable to the current user

 

 

 

 

Related command(s): CMSENCRYPT

See also: TLS Certificates menu, Import Certificate