<?xml version="1.0" encoding="iso-8859-1" standalone="no" ?> 
<!DOCTYPE document SYSTEM "rml_1_0.dtd"> 
<document filename="PdfEncryptIntro.pdf"> 
<!-- Last Modified:             $Date$ -->
<!-- Document Version Number:   $Revision$            -->

<template pageSize="(595, 842)" 
        leftMargin="72" 
        showBoundary="0"
        title="Pdfencrypt Info"
        author="Reportlab Inc"
        >

    <pageTemplate id="cover">
    <pageGraphics>
        <setFont name="Times-Bold" size="48"/>
        <drawCentredString x="297" y="516">PDF Encryption</drawCentredString>
        <setFont name="Times-Bold" size="12"/>
        <drawCentredString x="297" y="414">pdfencrypt info</drawCentredString>

        <lines>
        72 132 523 132
        </lines>

        <image file="replogo.gif" x="155" y="626"/>

        <setFont name="Times-Roman" size="10"/>
        <drawString x="72" y="110">Lombard Business Park</drawString>
        <drawString x="72" y="98">8 Lombard Road</drawString>
        <drawString x="72" y="86">Wimbledon</drawString>
        <drawString x="72" y="74">London, ENGLAND SW19 3TZ</drawString>

        <drawRightString x="523" y="110">103 Bayard Street</drawRightString>
        <drawRightString x="523" y="98">New Brunswick</drawRightString>
        <drawRightString x="523" y="86">New Jersey, 08901</drawRightString>
        <drawRightString x="523" y="74">USA</drawRightString>
    </pageGraphics>
    <frame id="first" x1="72" y1="72" width="451" height="698"/>
    </pageTemplate>

    <pageTemplate id="contents">
    <pageGraphics>
    </pageGraphics>
    <frame id="first" x1="72" y1="72" width="451" height="698"/>
    </pageTemplate>

    <pageTemplate id="inside">
    <pageGraphics>
        <lines>
        72 796 523 796
        </lines>
        <setFont name="Times-Roman" size="10"/>
        <drawString x="72" y="808">Pdfencrypt Info</drawString>
        <drawRightString x="523" y="808">$Revision$</drawRightString>
        <drawCentredString x="297.5" y="60">Page <pageNumber/></drawCentredString>
    </pageGraphics>
    <frame id="first" x1="72" y1="72" width="451" height="698"/>
    </pageTemplate>

</template>

<stylesheet>
    <initialize>
            <alias id="style.normal" value="style.Normal"/>
    </initialize>

    <paraStyle name="style.h1"
    fontName="Times-Bold"
    fontSize="20"
    leading="36"
    />

    <paraStyle name="style.h2"
    fontName="Times-Bold"
    fontSize="20"
    leading="36"
    />

    <paraStyle name="style.h3"
    fontName="Times-Bold"
    fontSize="12"
    leading="15"
    />

    <paraStyle name="contents"
    fontName="Times-Bold"
    fontSize="12"
    />

    <paraStyle name="contents2"
    fontName="Times-Roman"
    fontSize="12"
    leftIndent="20"
    />

    <paraStyle name="contents2a"
    fontName="Times-Roman"
    fontSize="12"
    leftIndent="20"
    spaceAfter="12"
    />

    <paraStyle name="contents2h"
    fontName="Times-Bold"
    fontSize="12"
    leftIndent="20"
    />
    
    <paraStyle name="contents3"
    fontName="Times-Roman"
    fontSize="12"
    leftIndent="40"
    leading="14.5"
    />

    <paraStyle name="contents3a"
    fontName="Times-Roman"
    fontSize="12"
    leftIndent="40"
    spaceAfter="12"
    />

    <paraStyle name="contents3h"
    fontName="Times-Bold"
    fontSize="12"
    leftIndent="40"
    />

    <paraStyle name="style.Normal"
    fontName="Times-Roman"
    fontSize="10"
    leading="12"
    spaceAfter="12"
    firstLineIndent="0"
    />

    <paraStyle name="programListing"
    parent="style.Normal"
    fontName="Courier-Bold"
    fontSize="8"
	leading="10"
    spaceBefore="2"
    spaceAfter="10"
    textColor="darkblue"
    leftIndent="1.2cm"
    />

    <paraStyle name="programListingConventionLabel"
    parent="programListing"
	spaceAfter="0"
    leftIndent="0"
    />
	
    <paraStyle name="bulletList" 
    parent="style.Normal" 
    bulletFontName="ZapfDingbats"
    bulletFontSize="5"
    bulletIndent="20"
    leftIndent="35"
    spaceAfter="6"
    />

    <paraStyle name="bulletNospace" 
    parent="bulletList" 
    spaceAfter="0"
    />
    
    <paraStyle name="nospace" 
    spaceAfter="0"
    parent="style.Normal" 
    />
    
    <paraStyle name="figureCaption" 
    spaceBefore="0"
    spaceAfter="15"
    alignment="CENTER"
    fontSize="8"
    fontName="Times-Italic"
    />
    
    <paraStyle name="paddingTableStyle"
	fontName="Helvetica-BoldOblique"
	fontSize="10"
	textColor="white"
	alignment="CENTER"
	/>

    <blockTableStyle id="simpleStyle">
    <blockFont name="Times-Roman" size="9" start="0,1" stop="-1,-1"/>
    <blockFont name="Times-Bold" size="9" start="0,0" stop="-1,0"/>
    <lineStyle kind="GRID" colorName="grey"/>
    <blockTextColor colorName="black"/>
    <blockTextColor colorName="white" start="0,0" stop="-1,0"/>
    <blockBackground colorName="grey" start="0,0" stop="-1,0"/>
    <blockValign value="top"/>
    </blockTableStyle>

</stylesheet>


<story>

<outlineAdd level="0">Pdfencrypt Info</outlineAdd>
<setNextTemplate name="cover"/>

<setNextTemplate name="contents"/>
<nextFrame/>

<h1>Pdfencrypt Info</h1>
<outlineAdd level="1">Contents</outlineAdd>

<h2>Contents</h2>

<para style="contents2a">
<name id="chapterNumber" value="1"/>
<seqReset id="sectionNumber"/>
<getName id="chapterNumber"/>.<seq id="sectionNumber"/>
What is Pdfencrypt for?
</para>

<para style="contents2a">
<getName id="chapterNumber"/>.<seq id="sectionNumber"/>
About encrypting PDF files
</para>

<para style="contents2">
<getName id="chapterNumber"/>.<seq id="sectionNumber"/>
How do I use PdfEncrypt?
</para>

<para style="contents3">
Command line usage
</para>

<para style="contents3">
Calling from Python
</para>

<para style="contents3">
Use with the reportlab library
</para>

<para style="contents3a">
Calling from other commercial ReportLab products (RML2PDF and PageCatcher)
</para>

<para style="contents2a">
<getName id="chapterNumber"/>.<seq id="sectionNumber"/>
Known Deficiencies and Caveats
</para>

<para style="contents2a">
<getName id="chapterNumber"/>.<seq id="sectionNumber"/>
Demo Modes
</para>

<para style="contents2a">
<getName id="chapterNumber"/>.<seq id="sectionNumber"/>
Feedback
</para>

<para style="contents2a">
<getName id="chapterNumber"/>.<seq id="sectionNumber"/>
Appendix: about Acrobat Encryption
</para>

<setNextTemplate name="inside"/>
<nextFrame/>

<h1>Pdfencrypt Info</h1>
<para>August 2002</para>

<para>
This document provides a basic introduction to using PdfEncrypt. It
includes explanations of what PdfEncrypt does, how it can be used,
what the current limitations are, how to run PdfEncrypt as a command
line program, how to use PdfEncrypt with the ReportLab RML2PDF and
PageCatcher applications, and how to use the Pdfencrypt programming
interface within other programs.
</para>

<h2>What is PdfEncrypt for?</h2>
<outlineAdd level="1">What is PdfEncrypt for?</outlineAdd>

<para>
PdfEncrypt is an add-on utility for ReportLab's suite of enterprise
reporting tools.  It allows you to encrypt PDF files, add user and
owner passwords and allow or prevent users access to certain
capabilities such as printing the file or copying and pasting from the
file.
</para>

<para>
How can this be useful in the real world? Imagine a situation where
you are generating customised reports with sensitive customer-specific
information (for example a bank statement). PdfEncrypt makes it
possible for your user to get a PDF file with the same password that
they use to login to your web site which is safe and secure to send
out by email.
</para>

<para>
Consider revenue protection. Imagine you are an organisation which
sells market research reports for $500 each. Your customers will find
it a lot less easy to pass your reports around if the front page of
each report is customised to say "prepared exclusively for Fred
Bloggs, no one else should see this" and it's password protected with
a password like "fbloggs:v1J99x"
</para>

<para>
For maximum effect, combine PdfEncrypt with our PageCatcher product,
and either our Open Source Library or RML2PDF to personalize as well
as protect.
</para>

<h2>About encrypting PDF files</h2>
<outlineAdd level="1">About encrypting PDF files</outlineAdd>

<para spaceAfter="0">
Adobe's PDF standard allows you to do three related things to a PDF
file when you encrypt it:
</para>
<para style="bulletList" bulletText="l" spaceAfter="0">
Apply password protection to it, so a user must supply a valid
password before being able to read it,
</para>
<para style="bulletList" bulletText="l" spaceAfter="0">
Encrypt the contents of the file to make it useless until it is
decrypted, and
</para>
<para style="bulletList" bulletText="l">
Control whether the user can print, copy and paste or modify the
document while viewing it.
</para>
   
<para spaceAfter="0">
The PDF security handler allows two different passwords to be specified for a document:
</para>
<para style="bulletList" bulletText="l" spaceAfter="0">
The 'owner' password (<i>aka</i> the 'security password' or 'master password')
</para>
<para style="bulletList" bulletText="l">
The 'user' password (<i>aka</i> the 'open password')
</para>

<para spaceAfter="0">

When a user supplies either one of these passwords, the PDF file will
be opened, decrypted and displayed on screen. If the owner password is
supplied, then the file is opened with full control - you can do
anything to it, including changing the security settings and
passwords, or re-encrypting it with a new password. If the user
password was the one that was supplied, you open it up in a more
restricted mode. The restrictions were put in place when the file was
encrypted, and will either allow or deny the user permission to do the
following:
</para>

<para style="bulletList" bulletText="l" spaceAfter="0">
Modifying the document's contents,
</para>
<para style="bulletList" bulletText="l" spaceAfter="0">
Copying text and graphics from the document,
</para>
<para style="bulletList" bulletText="l" spaceAfter="0">
Adding or modifying text annotations and interactive form fields,
</para>
<para style="bulletList" bulletText="l">
Printing the document.
</para>

<para>

Note that all password protected PDF files are encrypted, but not all
encrypted PDFs are password protected. If a document's user password
is an empty string, there will be no prompt for the password when the
file is opened. If you only secure a document with the owner password,
there will also not be a prompt for the password when you open the
file. If the owner and user passwords are set to the same string when
encrypting the PDF file, the document will always open with the user
access privileges. This means that it is possible to create a file
which, for example, is impossible for anyone to print out, even the
person who created it.
</para>

<blockTable
colWidths="90, 90, 260"
style="simpleStyle"
>
<tr>
   <td><para spaceAfter="0" textColor="white"><b>Owner password</b></para><para textColor="white"><b>set?</b></para></td>
   <td><para spaceAfter="0" textColor="white"><b>User password</b></para><para textColor="white"><b>set?</b></para></td>
   <td><para spaceAfter="0" textColor="white"><b>Result</b></para></td>
</tr>
<tr>
   <td>Y</td>
   <td>-</td>
   <td>
      <para spaceAfter="0">No password required when opening file.</para>
      <para>Restrictions apply to everyone.</para>
   </td>
</tr>
<tr>
   <td>-</td>
   <td>Y</td>
   <td>
      <para spaceAfter="0">User password required when opening the file.</para>
      <para>Restrictions apply to everyone.</para>
   </td>
</tr>
<tr>
   <td>Y</td>
   <td>Y</td>
   <td>
      <para spaceAfter="0">A password required when opening the file.</para>
      <para>Restrictions apply only if user password supplied.</para>
   </td>
</tr>
</blockTable>

<spacer length="12"/>
<condPageBreak height="45"/>
<para>
When a PDF file is encrypted, encryption is applied to all the strings
and streams in the file. This prevents people who don't have the
password from simply removing the password from the PDF file to gain
access to it - it renders the file useless unless you actually have
the password. PDF's standard encryption methods use the MD5 message
digest algorithm (as described in RFC 1321, <i>The MD5 Message-Digest
Algorithm</i>) and an encryption algorithm known as RC4. RC4 is a
symmetric stream cipher - the same algorithm is used both for
encryption and decryption, and the algorithm does not change the
length of the data.
</para>




<blockTable
colWidths="40, 430"
>
<tr><td>
<illustration width="32" height="21">
<image file="key.gif" x="1" y="1" width="30" height="19"/>
</illustration>
</td><td>
<para>
If an encrypted PDF file is opened using Adobe Acrobat (but not
Acrobat Reader), a small yellow key appears in the bottom status bar.
</para>
</td></tr>
</blockTable>

<nextFrame/>


<h2>How do I use PdfEncrypt?</h2>
<outlineAdd level="1">How do I use PdfEncrypt?</outlineAdd>

<h3>Command line usage</h3>
<outlineAdd level="2">Command line usage</outlineAdd>

<para spaceAfter="0">From a Windows command prompt ('DOS box'), type the following</para>
<pre style="programListing">pdfencrypt.exe -h</pre>
<para spaceAfter="0">From a Unix shell, type the following</para>
<pre style="programListing">python pdfencrypt.pyc -h</pre>

<para>This produces a usage reminder which should look like the one below:</para>
   
<pre style="programListing">
C:\Python\rlextra\utils>pdfencrypt.exe -h
PDFENCRYPT USAGE:

PdfEncrypt encrypts your PDF files.

Line mode usage:

% pdfencrypt.exe pdffile [-o ownerpassword] | [owner ownerpassword],
        [-u userpassword] | [user userpassword],
        [-p 1|0] | [printable 1|0],
        [-m 1|0] | [modifiable 1|0],
        [-c 1|0] | [copypastable 1|0],
        [-a 1|0] | [annotatable 1|0],
        [-s savefilename] | [savefile savefilename],
        [-v 1|0] | [verbose 1|0],
        [-e128], [encrypt128],
        [-h] | [help]

-o or owner set the owner password.
-u or user set the user password.
-p or printable set the printable attribute (must be 1 or 0).
-m or modifiable sets the modifiable attribute (must be 1 or 0).
-c or copypastable sets the copypastable attribute (must be 1 or 0).
-a or annotatable sets the annotatable attribute (must be 1 or 0).
-s or savefile sets the name for the output PDF file
-v or verbose prints useful output to the screen.
      (this defaults to 'pdffile_encrypted.pdf').
'-e128' or 'encrypt128' allows you to use 128 bit encryption (in beta).

-h or help prints this message.

See PdfEncryptIntro.pdf for more information.


C:\Python\rlextra\utils>
</pre>

<para>
This should tell you most of what you need to know about the command
line options for PdfEncrypt, but here are some more specific notes on
them
</para>

<para style="bulletList" bulletText="l">
The first argument after pdfencrypt should always be the
filename of the input file (referred to as <font face="Courier">pdffile</font> above).
This should be an unencrypted PDF file.
</para>

<para style="bulletList" bulletText="l">
All arguments other than the input filename have both a long
version (a memorable word) and a short version (beginning with a minus
sign, and shorter to type). Both versions will act in exactly the same manner.
</para>

<para style="bulletList" bulletText="l">
All arguments other than the input filename are optional (but you must
use at least one of them - there's no point giving pdfencrypt a
filename but not telling it what to do with it!). Where arguments are
given, they should be separated by a space (eg '<font
face="Courier">-s outfile.pdf</font>' rather than '<font
face="Courier">-soutfile.pdf</font>' or '<font
face="Courier">-s:outfile.pdf</font>').
</para>

<para style="bulletList" bulletText="l">
The output file should be specified using the '<font
face="Courier">-s</font>' or '<font face="Courier">savefile</font>'
argument. If no savefile argument is given, the filename for the
output file defaults to the input filename with the suffix of '<font
face="Courier">_encrypted.pdf</font>' added.
</para>


<para style="bulletList" bulletText="l">
If the '<font face="Courier">-o</font>' or '<font
face="Courier">owner</font>' argument is given, the word following
this becomes the owner password (see the section headed 'About
encrypting PDF files' for more information about owner passwords).
</para>

<para style="bulletList" bulletText="l">
If the '<font face="Courier">-u</font>' or '<font
face="Courier">user</font>' argument is given, the word following this
becomes the user password (see the section headed 'About encrypting
PDF files' for more info).
</para>

<para style="bulletList" bulletText="l">
The remaining arguments act as flags, switching on or off an ability
when the user views the encrypted PDF. For all of these, the argument
must be followed by a '<font face="Courier">0</font>' (to switch it
off), or a '<font face="Courier">1</font>' to switch it on. The
default for all of these is 1 (enabled). The arguments affected by
this are:
</para>

<para style="bulletList" spaceAfter="0">
'<font face="Courier">-a</font>', '<font face="Courier">annotatable</font>',
</para>

<para style="bulletList">
   (These turn on or off the user's ability to add new or modify existing text annotations and interactive form fields),
</para>

<para style="bulletList" spaceAfter="0">
'<font face="Courier">-c</font>', '<font face="Courier">copypastable</font>', 
</para>

<para style="bulletList">
   (These turn on or off the user's ability to copy and paste text and/or images from the document), 
</para>

<para style="bulletList" spaceAfter="0">
'<font face="Courier">-m</font>', '<font face="Courier">modifiable</font>', 
</para>

<para style="bulletList">
   (These turn on or off the user's ability to modify the documents contents),
</para>

<para style="bulletList" spaceAfter="0">
'<font face="Courier">-p</font>', '<font face="Courier">printable</font>'
</para>

<para style="bulletList">
   (These turn on or off the user's ability to print out the document).
</para>

<spacer length="12"/>

<h3>Examples</h3>

<para>
The following example encrypts the file 'test.pdf', giving it an owner
password of 'SPAM!' and a user password of "SPAM". The -v flag sets
the 'verbose' attribute so output is echoed onto the screen (giving us
some feedback). We are setting the Modifiable and Copypastable
attributes to zero, but still allowing the user who opens the output
PDF to annotate it and print it out. Because we haven't given an
output filename, the output PDF defaults to 'test_encrypted.pdf'
('test' plus the suffix of '_encrypted.pdf').
</para>

<pre style="programListing">
C:\Python\rlextra\utils>pdfencrypt.exe test.pdf -v 1 -o SPAM! -u SPAM -m 0 -c 0
Owner password set to: 'SPAM!'.
User password set to: 'SPAM'.
'Modifiable' set to: '0'.
'Copypastable' set to: '0'.
wrote output file 'test_encrypted.pdf'(42410 bytes)
  owner password is 'SPAM!'
  user password is 'SPAM!'

C:\Python\rlextra\utils>
    
</pre>

<para>
The following example also encrypts the file 'test.pdf', but uses the
longer versions of the arguments. The user password is set to "Eggs".
The owner password is set to "I DON'T LIKE SPAM!" - notice how it has
to be included in quotation marks since it contains spaces. Printable
is set to 0 - the other document attributes will stay at the default 1,
allowing the user to annotate, copy and paste and modify the document.
Here we do specify the output filename - 'nospam.pdf'.     
</para>

<pre style="programListing">
C:\Python\rlextra\utils>pdfencrypt.exe test.pdf user Eggs owner "I DON'T LIKE SPAM!"
verbose 1 printable 0 savefile nospam.pdf
Owner password set to: 'I DON'T LIKE SPAM!'.
User password set to: 'Eggs'.
'Printable' set to: '0'.
Output file set to: 'nospam.pdf'.
wrote output file 'nospam.pdf'(42456 bytes)
  owner password is 'I DON'T LIKE SPAM!'
  user password is 'Eggs'

C:\Python\rlextra\utils>
    
</pre>

<para>
Another example. This one is identical to the previous one,
only using the short form of the arguments. It also differs in that
the verbose flag is set to 0, so no output is produced. This can be
useful in situations where printing to the standard output is not
desirable.
</para>

<pre style="programListing">
C:\Python\rlextra\utils>pdfencrypt.exe test.pdf -u Eggs -o "I DON'T LIKE SPAM!" -v 0 
-p 0 -s nospam.pdf

C:\Python\rlextra\utils>dir *.pdf
 Volume in drive C has no label.
 Volume Serial Number is 07D1-020F

 Directory of C:\Python\rlextra\utils

20/08/2002  17:24               42,409 nospam.pdf
               1 File(s)         42,409 bytes
               0 Dir(s)   3,125,477,376 bytes free

C:\Python\rlextra\utils>
    
</pre>    

<para>
One last example. When you do not have a licensed copy of
PdfEncrypt, the passwords default to hardcoded ones:
</para>

<pre style="programListing">
C:\Python\rlextra\utils>pdfencrypt.exe test.pdf -u Eggs -o "I DON'T LIKE SPAM!" -v
1 -p 0 -s nospam.pdf
Owner password set to: 'This is Unlicensed Software' (evaluation version).
User password set to: 'Mr Unlicensed Software' (evaluation version).
'Printable' set to: '1' (evaluation version).
Output file set to: 'encrypted.pdf' (evaluation version).
wrote output file 'test_encrypted.pdf'(42434 bytes)
  owner password is 'This is Unlicensed Software'
  user password is 'Mr Unlicensed Software'

C:\Python\rlextra\utils>

</pre>
    
<!--condPageBreak height="45"/-->
<nextFrame/>
    
<h3>Calling from Python</h3>
<outlineAdd level="2">Calling from Python</outlineAdd>

<para spaceAfter="0">
From Python, you need to import the pdfencrypt module before you can do anything with it.
</para>    
<pre style="programListing">import rlextra.utils.pdfencrypt</pre>

<para>
Once this is done, you can use the functions <i>encryptPdfOnDisk</i> and <i>encryptPdfInMemory</i>:
</para>

<para><b>encryptPdfOnDisk</b></para>
<para>
This creates the output PDF on disk. The argument footprint looks like this:
</para>    
<pre style="programListing">encryptPdfOnDisk(inputFileName, outputFileName, userPassword,
                 ownerPassword=None, canPrint=1, canModify=1, canCopy=1, canAnnotate=1)

</pre>    
<blockTable>
<tr><td>inputFileName</td><td>The name of the input PDF file (required).</td></tr>
<tr><td>outputFileName</td><td>The name to be used for the output (encrypted) PDF file (required).</td></tr>
<tr><td>userPassword</td><td>The user password to be used (required)</td></tr>
<tr><td>ownerPassword</td><td>The owner password to be used (optional).</td></tr>
<tr><td>canPrint</td><td>Can the user print the output PDF? (defaults to 1)</td></tr>
<tr><td>canModify</td><td>Can the user modify the contents of output PDF? (defaults to 1)</td></tr>
<tr><td>canCopy</td><td>Can the user copy and paste text/images from the output PDF? (defaults to 1)</td></tr>
<tr><td>canAnnotate</td><td>Can the user make annotations on the output PDF? (defaults to 1)</td></tr>
</blockTable>

<spacer length="6"/>
<para><b>returns:</b> the length of the output PDF file in bytes.</para>
<para spaceAfter="0"><b>examples:</b></para>
<pre style="programListing">
C:\Python>python
Python 2.2.1 (#34, Apr  9 2002, 19:34:33) [MSC 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import rlextra.utils.pdfencrypt
>>> rlextra.utils.pdfencrypt.encryptPdfOnDisk('test.pdf', 'saved.pdf', 'SPAM',
canPrint=0)
42307

>>> from rlextra.utils.pdfencrypt import encryptPdfOnDisk
>>> encryptPdfOnDisk('test.pdf', 'saved2.pdf', 'SPAM', ownerPassword="SPAM!",
canPrint=0, canCopy=0)
42346
>>>
    
</pre>
<spacer length="12"/>


<para><b>encryptPdfInMemory</b></para>

<para>
This function accepts a PDF file 'as a byte array in memory', encrypts
it and returns encrypted one.
</para>    

<para>
This is a high level convenience and does not touch the hard disk in
any way. If you are encrypting the same file over and over again, it's
better to use PageCatcher and cache the results (see the later section
on how to use PdfEncrypt and PageCatcher).
</para>    

<para>
The argument footprint looks like this:
</para>    

<pre style="programListing">encryptPdfInMemory(inputPDF, userPassword, ownerPassword=None,
                  canPrint=1, canModify=1, canCopy=1, canAnnotate=1)

</pre>

<blockTable>
<tr><td>inputFileName</td><td>The name of the input byte array (required).</td></tr>
<tr><td>userPassword</td><td>The user password to be used (required)</td></tr>
<tr><td>ownerPassword</td><td>The owner password to be used (optional).</td></tr>
<tr><td>canPrint</td><td>Can the user print the output PDF? (defaults to 1)</td></tr>
<tr><td>canModify</td><td>Can the user modify the contents of output PDF? (defaults to 1)</td></tr>
<tr><td>canCopy</td><td>Can the user copy and paste text/images from the output PDF? (defaults to 1)</td></tr>
<tr><td>canAnnotate</td><td>Can the user make annotations on the output PDF? (defaults to 1)</td></tr>
</blockTable>

<spacer length="6"/>
<para><b>returns:</b> an encrypted version of the input array.</para>
<para spaceAfter="0"><b>example:</b></para>
<pre style="programListing">
C:\Python>python
Python 2.2.1 (#34, Apr  9 2002, 19:34:33) [MSC 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import rlextra.utils.pdfencrypt
>>> input = open('test.pdf', 'rb').read()
>>> output = rlextra.utils.pdfencrypt.encryptPdfInMemory(input, 'SPAM', canPrint=0)
>>>

>>> from rlextra.utils.pdfencrypt import encryptPdfInMemory
>>> output2 = encryptPdfInMemory(input, 'SPAM', ownerPassword="SPAM!", canPrint=0,
canCopy=0)
>>>

</pre>
<spacer length="12"/>

<h3>Use from the ReportLab Toolkit</h3>
<outlineAdd level="2">Use from the ReportLab Toolkit</outlineAdd>

<para>
The ReportLab toolkit is our free, Open Source library for creating
PDFs from Python. You can use the function <i>encryptCanvas</i> and
the class <i>EncryptionFlowable</i> with it.
</para>

<para><b>encryptCanvas</b></para>
<para>
The encryptCanvas applies encryption to the document being generated.
You must pass in a reportlab canvas object, which it then encrypts.
</para>

<para>
The argument footprint looks like this:
</para>    

<pre style="programListing">encryptCanvas(canvas, userPassword, ownerPassword=None,
                  canPrint=1, canModify=1, canCopy=1, canAnnotate=1)

</pre>

<blockTable>
<tr><td>canvas</td><td>The canvas to be encrypted (required).</td></tr>
<tr><td>userPassword</td><td>The user password to be used (required)</td></tr>
<tr><td>ownerPassword</td><td>The owner password to be used (optional).</td></tr>
<tr><td>canPrint</td><td>Can the user print the output PDF? (defaults to 1)</td></tr>
<tr><td>canModify</td><td>Can the user modify the contents of output PDF? (defaults to 1)</td></tr>
<tr><td>canCopy</td><td>Can the user copy and paste text/images from the output PDF? (defaults to 1)</td></tr>
<tr><td>canAnnotate</td><td>Can the user make annotations on the output PDF? (defaults to 1)</td></tr>
</blockTable>

<spacer length="6"/>
<para><b>returns:</b> None.</para>
<para spaceAfter="0"><b>example:</b></para>

<pre style="programListing">
C:\Python\rlextra\utils>python
Python 2.2.1 (#34, Apr  9 2002, 19:34:33) [MSC 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> from reportlab.pdfgen import canvas
>>> c = canvas.Canvas("hello.pdf")
>>> from rlextra.utils.pdfencrypt import encryptCanvas
>>> encryptCanvas(c, "SPAM")
>>> c.drawCentredString(297, 420, "Hello World")
>>> c.showPage()
>>> c.save()

</pre>


<para><b>EncryptionFlowable</b></para>
<para>
This class is a flowable, and can be used just like an other
flowables. It can be dropped into your Platypus story and it will set
up the encryption options. Like other flowables, it has to be drawn
onto the canvas (see below for an example of how to do this).
</para>

<para>
If you have multiple instances of EncryptionFlowable in a document,
then the encryption setting that are used come from the last one to be called.
</para>

<para>
See Chapter 5 of the ReportLab User Guide for more information on using Platypus)
</para>

<para>
The argument footprint for starting an new instance of EncryptionFlowable looks like this:
</para>    

<pre style="programListing">EncryptionFlowable(canvas, userPassword, ownerPassword=None,
                  canPrint=1, canModify=1, canCopy=1, canAnnotate=1)

</pre>

<blockTable>
<tr><td>canvas</td><td>The canvas to be encrypted (required).</td></tr>
<tr><td>userPassword</td><td>The user password to be used (required)</td></tr>
<tr><td>ownerPassword</td><td>The owner password to be used (optional).</td></tr>
<tr><td>canPrint</td><td>Can the user print the output PDF? (defaults to 1)</td></tr>
<tr><td>canModify</td><td>Can the user modify the contents of output PDF? (defaults to 1)</td></tr>
<tr><td>canCopy</td><td>Can the user copy and paste text/images from the output PDF? (defaults to 1)</td></tr>
<tr><td>canAnnotate</td><td>Can the user make annotations on the output PDF? (defaults to 1)</td></tr>
</blockTable>

<pre style="programListing">
from reportlab.pdfgen import canvas
from reportlab.lib.styles import getSampleStyleSheet
from reportlab.platypus import Paragraph
from rlextra.utils.pdfencrypt import EncryptionFlowable
styleSheet = getSampleStyleSheet()
style = styleSheet['BodyText']
P1=Paragraph('This is an encrypted document. ',style)
aW = 460
aH = 800
c = canvas.Canvas("hello.pdf")
ef = EncryptionFlowable('SPAM', ownerPassword="SPAM!")
w,h = P1.wrap(aW, aH)
P1.drawOn(c,20,aH)
ef.drawOn(c,20,aH)
c.save()

</pre>

<spacer length="12"/>


<nextFrame/>
<h3>Calling from other commercial ReportLab products (RML2PDF and PageCatcher)</h3>
<outlineAdd level="2">Calling from other commercial ReportLab products</outlineAdd>

<para><b>PageCatcher</b></para>
<pre>To do</pre>

<!--pre>
    from rlextra.pageCatcher.pageCatcher import storeForms
    storeForms("encrypted.pdf", "dump.temp", password="User")
</pre -->

<para><b>RML2PDF</b></para>
<pre>To do</pre>
<!-- pre>
def go(xmlInputText, outputFileName=None, outDir=None, dtdDir=None,
       passLimit=2, permitEvaluations=1, ignoreDefaults=0,
       pageCallBack=None,
       progressCallBack=None,
       preppyDictionary=None, preppyIterations=1,
       encryption=None,
       verbose=0):
</pre>
<pre>
    If encryption is set it must be an encryption object.
    For example
    rlextra.utils.pdfencrypt.StandardEncryption("User", "Owner", canPrint=0, canModify=0, canCopy=0, canAnnotate=0)
</pre-->




<!--para>The commercial product consists of a compiled Python module
(similar to a Java class file) which can be used in 3 ways:</para>
<para style="bulletList" bulletText="l">as a command line application with many useful options</para>
<para style="bulletList" bulletText="l">as a library within Python scripts</para>
<para style="bulletList" bulletText="l">controlled by tags within RML documents</para-->

<!--para>The PageCatcher product
can either function as a module in a larger Python installation
(which should include the ReportLab core libraries), or as a
stand alone executable which contains the ReportLab distribution
and all other required software components.</para-->

<!--para>
In either mode you can write your own
scripts as well as looking at the ones we provided.
Please consult the first few chapters of the <b>Reportlab User Guide</b>,
and to look at the documentation for the <b>Python</b> scripting language
for additional information on using the ReportLab toolkit and the Python
programming language.</para-->

<!--para
PageCatcher also functions as a add on component to the RML2PDF program
supported by the <i>catchForms</i> RML tag.
Please see the RML2PDF userguide for more information on using RML2PDF.
para-->


<nextFrame/>
<h2>Known Deficiencies and Caveats</h2>
<outlineAdd level="1">Known Deficiencies and Caveats</outlineAdd>

<para>
If the owner password is not set, and the user password <i>is</i> set,
then PdfEncrypt will set both passwords to the user password. Since
they will both the same, the file will always open with the user
access privileges. This means that it is possible to create encrypted
files for which nobody has permission to modify, print etc.
</para>

<h2>Demo Modes</h2>
<outlineAdd level="1">Demo Modes</outlineAdd>

<para>
If you have not purchased a license for PdfEncrypt, you are still able
to use it. However, all the user restrictions will be set to 1 (so for
example, you won't be able to prevent a user printing out a document).
Also, if you set the user password it will be reset to a hardcoded one
(currently 'Mr Unlicensed Software'), and if you set an owner
password, it will be set to the hardcoded 'This is Unlicensed
Software'.
</para>

<para>                                                                
All these restrictions are removed if you purchase a license. Email
info@reportlab.com for more details.
</para>
                                                                
<h2>Feedback</h2>
<outlineAdd level="1">Feedback</outlineAdd>

<para>
We need and welcome feedback to help make this into a great product!  Email 
info@reportlab.com, or join our group of 200+ existing users by emailing
reportlab-users@reportlab.com (with 'Subscribe' in the subject line), or
join from the web interface at http://two.pairlist.net/mailman/listinfo/reportlab-users.</para>

<para>Enjoy!</para>

<nextFrame/>

<h2>Appendix: about Acrobat Encryption</h2>
<outlineAdd level="1">Appendix: about Acrobat Encryption</outlineAdd>

<pre>To do</pre>
 
</story>

</document>
