CASI Software's Hints and Tips
PDF File Embedding
and AES Encryption
This how-to article focuses on two enhancements that became
available in the 4.5.0 version of JES2Mail/JES2FTP. The first is the ability to embed files into
a PDF document. Adobe refers to this as
attaching files but because we use the term attachment to refer to a file
attached to an email message we are using the term “embedded” in its
place. It is a descriptive term since
the embedded files are placed inside the PDF file that is created and, in the
case of JES2Mail, attached to an email message.
The second enhancement is the added encryption level of AES that is now
supported by JES2Mail and JES2FTP when creating PDF documents.
To demonstrate the file embedding process we’ll expand on the first
how-to article that was distributed and that is the process of creating a
comma-delimited (.csv) spreadsheet file from a report. This process will create the .csv file and
embed it into the PDF copy of the report that is produced. All that is required to embed the .csv file
into the PDF document is the addition of a PDFEmbed statement in the script
that is used and we’ll see that shortly.
The ruleset that processes the report does not require any changes and
it contains the following statements:
Name:
Comma Delimited Extract
PackageType:
PDF
From:
jes2mail@casisoft.com
Font:
Courier
FontSize:
Medium
PageSize:
Letter
Orientation:
Landscape
Script:
DD:SCRIPT
This ruleset contains the basic statements to create a PDF document
from a typical, 133-column, report. The
script file, located at the SCRIPT DD statement in our job, contains these
statements:
)InitialPage
ZExtractFileName
= 'sales.csv'
ExtractData(Comma,
" ", 5:2, 5:134)
)OnEachPage
ExtractData(Comma,
"25x,11x,13x,13x,13x,13x,13x,13x,13x", 7:2)
Outputpage
)OnsubReportBegin
PDFEmbed("Extract.txt", ZExtractFilename, text, trim,
-
"Copy for
Excel")
The report that this script is designed to process is the “sales4pg” report
located in our SAMPRPT library.
An OnSubReportBegin section has been added to the script and this
new section contains a PDFEmbed statement.
The reason that the PDFEmbed statement has been placed into an
OnSubReportBegin section rather than in the InitialPage section is to allow for
possible splitting of the report. If the
report were being split then it is likely that the .csv file would require
splitting also. This would necessitate
placing the PDFEmbed statement in the OnSubReportBegin section and since the
statement works equally well in this section regardless of whether the report
is being split or not it is a good habit to make to always use this section for
this purpose. The PDFEmbed statement
uses the file name of “Extract.txt” as the file to be embedded. This file name has special meaning to
JES2Mail/FTP and always refers to the internal file being created through the
ExtractData statements. The second
parameter represents the name of the file that will be carried inside the PDF
document. This value has already been
placed into the ZExtractFilename system variable so we simply use that variable
name here. The “text” parameter
indicates that the file is a text file and will be converted to ASCII and that
CR/LF characters will added to each line.
The “trim” value indicates that trailing spaces on each line of the text
file will be removed. The last parameter
is a description string that will be used for display purposes when the PDF
document is opened.
When the resulting PDF document is opened inside Adobe Acrobat, the
report appears like this:
Notice that the Adobe Attachments indicator appears to illustrate
that our embedded file has been attached to this document. If you click on this indicator an attachments
window appears under the report itself, something like this:
Now we can see that our “sales.csv” file has been attached, or
embedded, into the PDF document itself.
If you double click on the .csv file here it will open up into Excel:
Multiple files can be embedded into a PDF document by having
multiple PDFEmbed statements within your script. For example, here is an expansion of the
previous script that adds the CASI logo jpeg file as an additional file
embedded into the PDF document:
)InitialPage
ZExtractFileName
= 'sales.csv'
ExtractData(Comma,
" ", 5:2, 5:134)
)OnEachPage
ExtractData(Comma,
"25x,11x,13x,13x,13x,13x,13x,13x,13x", 7:2)
Outputpage
)OnsubReportBegin
PDFEmbed("Extract.txt",
ZExtractFilename, text, trim, -
"Copy for Excel")
PDFEmbed("bend.pds.binary(casiljpg)",
"logo.jpg", binary, notrim, -
"Sample Binary
Embed")
The second PDFEmbed statement embeds a jpeg file that has been
uploaded to our host and specifies that it is a binary file so that no ASCII
translation or modification is performed on the file and that no attempt is to
be made to trim trailing spaces from within the file. The result is that when the PDF is opened and
the attachment icon clicked on in Acrobat, the following appears showing that
two files have been attached to this PDF document:
There are several aspects of the new file embedding feature of
JES2Mail/FTP that we feel make it an exciting new feature of the product. First is the transportability of the document
and attachments as one physical package.
There is no concern that one may get separated from the other. The second is that because the embedded
file(s) is located inside the PDF document itself, that the entire package can
be secured via the built-in Adobe PDF encryption algorithms. That brings us to the second major
enhancement added to the 4.5.0 version of the products.
The PDF encryption that has been available prior to version 4.5.0
included only the RC4 encryption algorithm in either a 40 or 128-bit level of
encryption. With Acrobat version 7 Adobe
began supporting the AES encryption algorithm, a superior encryption method to
RC4. JES2Mail/JES2FTP now support
encrypting PDF documents in the AES algorithm, which is always 128-bit. This is accomplished through the
“ProtectLevel: AES” statement in a ruleset.
By adding the ProtectLevel statement along with a ProtectUserPassword
statement to give a password value to our previous ruleset the entire package
of our PDF document and the embedded attachments can be encrypted using AES:
Name:
Comma Delimited Extract
PackageType:
PDF
From:
jes2mail@casisoft.com
Font:
Courier
FontSize:
Medium
PageSize:
Letter
Orientation:
Landscape
Script:
DD:SCRIPT
ProtectLevel: AES
ProtectUserPassword: casisoft
Action:
mail
When we open this PDF document in Acrobat we get the password
window instead of the document itself:
Once we enter our password “casisoft” into the window the document
appears just as before with all attachments available for our use:
The document, and all embedded files within it, remain encrypted so
that the security provided by encryption remains with the file during and after
the transmission of the file to its intended destination.
Please note that in order to use these new features it is necessary
to upgrade your JES2Mail/JES2FTP product to the 4.5.0 version level if you have
not already done so. Additionally, the
use of AES encryption requires that the recipient of the PDF document be using
Adobe’s Acrobat (or Acrobat Reader) version 7 or above.
If anyone has suggestions on subjects they would like to see
discussed in the how-to series, please email them to support@casisoft.com and we will
consider them for future use.