pdftron::SDF::SecurityHandler Class Reference

Standard Security Handler is a standard password-based security handler. More...

#include <SecurityHandler.h>

List of all members.

Public Types

enum  Permission {
  e_owner = 1, e_doc_open, e_doc_modify, e_print,
  e_print_high, e_extract_content, e_mod_annot, e_fill_forms,
  e_access_support, e_assemble_doc
}
enum  AlgorithmType { e_RC4_40 = 1, e_RC4_128, e_AES }
 The algorithm to be used in encrypting and decrypting the document. More...
enum  {
  has_CloneProc = 0x01, has_AuthProc = 0x02, has_AuthFailedProc = 0x04, has_GetAuthDataProc = 0x08,
  has_EditSecurDataProc = 0x10, has_FillEncDictProc = 0x20
}

Public Member Functions

bool GetPermission (Permission p)
int GetKeyLength () const
int GetEncryptionAlgorithmID () const
const char * GetHandlerDocName () const
bool IsModified () const
void SetModified (bool is_modified=true)
 The method allows derived classes to set SecurityHandler is modified flag.
 SecurityHandler (AlgorithmType crypt_type)
 Create a Standard Security Handler.
 SecurityHandler (const char *name, int key_len, int enc_code)
 Create a Standard Security Handler.
 SecurityHandler ()
 SecurityHandler (const SecurityHandler &s)
SecurityHandleroperator= (const SecurityHandler &)
virtual ~SecurityHandler ()
void ChangeUserPassword (const char *password)
 Modify the user password.
const char * GetUserPassword ()
void ChangeMasterPassword (const char *password)
 Modify the master password.
const char * GetMasterPassword ()
void SetPermission (Permission perm, bool value)
 Set the permission setting of the StdSecurityHandler.
void ChangeRevisionNumber (int rev_num)
 Change the revision number and the encryption algorithm of the standard security handler.
void SetEncryptMetadata (bool encrypt_metadata)
 Indicates whether the document-level metadata stream is to be encrypted.
int GetRevisionNumber ()
bool IsUserPasswordRequired ()
bool IsMasterPasswordRequired ()
bool IsAES () const
bool IsAES (Obj stream) const
 The following function can be used to verify whether a given stream is encrypted using AES.
bool IsRC4 () const
 operator bool ()
virtual void AuthorizeFailed ()
 A callback method indicating repeated failed authorization.
virtual bool Authorize (Permission p)
 The method is called when a user tries to set security for an encrypted document and when a user tries to open a file.
virtual bool GetAuthorizationData (Permission req_opr)
 This method is invoked in case Authorize() failed.
virtual bool EditSecurityData (SDFDoc &doc)
 Called when the security handler should activate a dialog box with the current security settings that may be modified.
virtual Obj FillEncryptDict (class SDFDoc &doc)
 Called when an encrypted document is saved.
virtual SecurityHandlerClone (TRN_SecurityHandler base) const
void InitPassword (const char *password)
 The method can be called in GetAuthorizationData() callback to specify user supplied password.
void SetDerived (UInt32 overloaded_funct)
 This method informs base security handler which methods are overridden in the derived class.
SecurityHandlerGetDerived () const


Detailed Description

Standard Security Handler is a standard password-based security handler.

Member Enumeration Documentation

Enumerator:
e_owner  the user has 'owner' rights (e.g. rights to change the document's security settings).
e_doc_open  open and decrypt the document.
e_doc_modify  edit the document more than adding or modifying text notes.
e_print  print the document.
e_print_high  high resolution print.
e_extract_content  enable content extraction
e_mod_annot  allow modifications to annotations
e_fill_forms  allow changes to fill in forms
e_access_support  content access for the visually impaired.
e_assemble_doc  allow document assembly

The algorithm to be used in encrypting and decrypting the document.

Enumerator:
e_RC4_40  40-bit RC4 algorithm.
e_RC4_128  128-bit RC4 algorithm.
e_AES  Use Crypt filters with 128-bit AES (Advanced Encryption Standard) algorithm.

anonymous enum

Enumerator:
has_CloneProc 
has_AuthProc 
has_AuthFailedProc 
has_GetAuthDataProc 
has_EditSecurDataProc 
has_FillEncDictProc 


Constructor & Destructor Documentation

pdftron::SDF::SecurityHandler::SecurityHandler ( AlgorithmType  crypt_type  ) 

Create a Standard Security Handler.

Parameters:
crypt_type The encryption algorithm identifier.

pdftron::SDF::SecurityHandler::SecurityHandler ( const char *  name,
int  key_len,
int  enc_code 
)

Create a Standard Security Handler.

Parameters:
key_len The bit length of the encryption key (40 or 128 bit).
enc_code The encryption algorithm identifier. The number corresponds to the V entry in encryption dictionary. Currently allowed values are (see Table 3.18 in PDF Reference Manual v1.6 for more details):
  • 1 : Encryption using 40-bit RC4 algorithm.
  • 2 : Encryption using 128-bit RC4 algorithm. Available in PDF 1.4 and above.
  • 3 : This algorithm was deprecated by PDF standard and is not supported.
  • 4 : Encryption using Crypt filters and 128-bit AES (Advanced Encryption Standard) algorithm. Available in PDF 1.6 and above.
values for key_len and enc_code are 128 and 2 respectively.

pdftron::SDF::SecurityHandler::SecurityHandler (  ) 

pdftron::SDF::SecurityHandler::SecurityHandler ( const SecurityHandler s  ) 

virtual pdftron::SDF::SecurityHandler::~SecurityHandler (  )  [virtual]


Member Function Documentation

bool pdftron::SDF::SecurityHandler::GetPermission ( Permission  p  ) 

Returns:
true if the SecurityHandler permits the specified action (Permission p) on the document, or false if the permission was not granted.
Parameters:
p A Permission to be granted.
Note:
in order to check for permission the method will repeatedly (up to three times) attempt to GetAuthorizationData() and Authorize() permission. If the permission is not granted AuthorizeFailed() callback will be called. This callback method allows derived class to provide UI feedback for failed authorization.

int pdftron::SDF::SecurityHandler::GetKeyLength (  )  const

Returns:
The length of the encryption key in bytes.
Note:
The returned key length is given in bytes.

int pdftron::SDF::SecurityHandler::GetEncryptionAlgorithmID (  )  const

Returns:
The encryption algorithm identifier. A code specifying the algorithm to be used in encrypting and decrypting the document. Returned number corresponds to V entry in encryption dictionary. Currently allowed values are from 0-4. See PDF Reference Manual for more details.

const char* pdftron::SDF::SecurityHandler::GetHandlerDocName (  )  const

Returns:
The name of the security handler as it appears in the serialized file as the value of /Filter key in /Encrypt dictionary.

bool pdftron::SDF::SecurityHandler::IsModified (  )  const

Returns:
- true if the SecurityHandler was modified (by calling SetModified()) or false otherwise.
If the user changes SecurityHandler's settings (e.g. by changing a password), IsModified() should return true.

void pdftron::SDF::SecurityHandler::SetModified ( bool  is_modified = true  ) 

The method allows derived classes to set SecurityHandler is modified flag.

This method should be called whenever there are changes (e.g. a password change) to the SecurityHandler

SecurityHandler& pdftron::SDF::SecurityHandler::operator= ( const SecurityHandler  ) 

void pdftron::SDF::SecurityHandler::ChangeUserPassword ( const char *  password  ) 

Modify the user password.

Parameters:
password the new user password

const char* pdftron::SDF::SecurityHandler::GetUserPassword (  ) 

Returns:
Current user password.

void pdftron::SDF::SecurityHandler::ChangeMasterPassword ( const char *  password  ) 

Modify the master password.

Parameters:
password the new master/owner password

const char* pdftron::SDF::SecurityHandler::GetMasterPassword (  ) 

Returns:
Current master password.

void pdftron::SDF::SecurityHandler::SetPermission ( Permission  perm,
bool  value 
)

Set the permission setting of the StdSecurityHandler.

Parameters:
perm indicates a permission to set or clear. It can be any of the following values:
e_print // print the document. e_doc_modify // edit the document more than adding or modifying text notes. e_extract_content // enable content extraction e_mod_annot // allow modifications to annotations e_fill_forms // allow changes to fill in forms e_access_support // content access for the visually impaired. e_assemble_doc // allow document assembly e_print_high // high resolution print.

Parameters:
value true if the permission/s should be granted, false otherwise.

void pdftron::SDF::SecurityHandler::ChangeRevisionNumber ( int  rev_num  ) 

Change the revision number and the encryption algorithm of the standard security handler.

Parameters:
rev_num the new revision number of the standard security algorithm. Currently allowed values for the revision number are (see Table 3.18 in PDF Reference Manual v1.6 for more details):
  • 2 : Encryption using 40-bit RC4 algorithm.
  • 3 : Encryption using 128-bit RC4 algorithm. Available in PDF 1.4 and above.
  • 4 : Encryption using Crypt filters and 128-bit AES (Advanced Encryption Standard) algorithm. Available in PDF 1.6 and above.

void pdftron::SDF::SecurityHandler::SetEncryptMetadata ( bool  encrypt_metadata  ) 

Indicates whether the document-level metadata stream is to be encrypted.

Parameters:
encrypt_metadata true if metadata stream should be encrypted, false otherwise.
Note:
EncryptMetadata flag affects only Crypt filters available in PDF 1.5 (Acrobat 6) and later. By default, metadata stream will be encrypted.

int pdftron::SDF::SecurityHandler::GetRevisionNumber (  ) 

Returns:
the revision number of the standard security algorithm.

bool pdftron::SDF::SecurityHandler::IsUserPasswordRequired (  ) 

Returns:
true if the SecurityHandler requires a user password.

bool pdftron::SDF::SecurityHandler::IsMasterPasswordRequired (  ) 

Returns:
true if the SecurityHandler requires a master (owner) password.

bool pdftron::SDF::SecurityHandler::IsAES (  )  const

Returns:
true is this security handler uses 128 bit AES (Advanced Encryption Standard) algorithm to encrypt strings or streams.

bool pdftron::SDF::SecurityHandler::IsAES ( Obj  stream  )  const

The following function can be used to verify whether a given stream is encrypted using AES.

Returns:
true if the given stream is encrypted using AES encryption.
Parameters:
stream A pointer to an SDF::Stream object

bool pdftron::SDF::SecurityHandler::IsRC4 (  )  const

Returns:
true is this security handler uses RC4 algorithm to encrypt strings or streams.

pdftron::SDF::SecurityHandler::operator bool (  )  [inline]

Returns:
true if the object is not null, false otherwise.

virtual void pdftron::SDF::SecurityHandler::AuthorizeFailed (  )  [virtual]

A callback method indicating repeated failed authorization.

Override this callback in order to provide a UI feedback for failed authorization. Default implementation returns immediately.

virtual bool pdftron::SDF::SecurityHandler::Authorize ( Permission  p  )  [virtual]

The method is called when a user tries to set security for an encrypted document and when a user tries to open a file.

It must decide, based on the contents of the authorization data structure, whether or not the user is permitted to open the file, and what permissions the user has for this file.

Note:
- This callback must not obtain the authorization data (e.g. by displaying a user interface into which a user can type a password). This is handled by the security handler’s GetAuthorizationData(), which must be called before this callback. Instead, Authorize() should work with authorization data it has access to.
Parameters:
p - permission to authorize

virtual bool pdftron::SDF::SecurityHandler::GetAuthorizationData ( Permission  req_opr  )  [virtual]

This method is invoked in case Authorize() failed.

The callback must determine the user’s authorization properties for the document by obtaining authorization data (e.g. a password through a GUI dialog).

The authorization data is subsequently used by the security handler’s Authorize() to determine whether or not the user is authorized to open the file.

Returns:
false if the operation was canceled, true otherwise.
Parameters:
req_opr - the permission for which authorization data is requested.

virtual bool pdftron::SDF::SecurityHandler::EditSecurityData ( SDFDoc doc  )  [virtual]

Called when the security handler should activate a dialog box with the current security settings that may be modified.

Returns:
true if the operation was successful false otherwise.

virtual Obj pdftron::SDF::SecurityHandler::FillEncryptDict ( class SDFDoc doc  )  [virtual]

Called when an encrypted document is saved.

Fills the document's Encryption dictionary with whatever information the security handler wants to store in the document.

The sequence of events during creation of the encrypt_dict is as follows:

  • encrypt_dict is created (if it does not exist)
  • Filter attribute is added to the dictionary
  • call this method to allow the security handler to add its own attributes
  • call the GetCryptKey to get the algorithm version, key, and key length
  • checks if the V attribute has been added to the dictionary and, if not, then sets V to the algorithm version
  • set the Length attribute if V is 2 or greater
  • add the encrypt_dict to the document

Parameters:
doc - The document to save.
Returns:
- encrypt_dict
Warning:
- Unlike all other strings and streams, direct object elements of the encrypt_dict are not encrypted automatically. If you want them encrypted, you must encrypt them before inserting them into the dictionary.

virtual SecurityHandler* pdftron::SDF::SecurityHandler::Clone ( TRN_SecurityHandler  base  )  const [virtual]

Returns:
A new, cloned instance of SecurityHandler.
Note:
this method must be implemented in any derived class from SecurityHandler.

void pdftron::SDF::SecurityHandler::InitPassword ( const char *  password  ) 

The method can be called in GetAuthorizationData() callback to specify user supplied password.

void pdftron::SDF::SecurityHandler::SetDerived ( UInt32  overloaded_funct  ) 

This method informs base security handler which methods are overridden in the derived class.

The only place this method needs to be invoked is in Create(name, key_len, enc_code) static factory method in the derived class.

Parameters:
overloaded_funct A flag that specifies which functions are overloaded in the derived class. For example: SetDerived(SecurityHandler::has_Clone + SecurityHandler::has_FillEncDictProc);

SecurityHandler* pdftron::SDF::SecurityHandler::GetDerived (  )  const

Returns:
The derived class or NULL for standard security handler.


© 2002-2010 PDFTron Systems Inc.