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

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