Loading...
Searching...
No Matches
pdftron::SDF::SecurityHandler Class Reference

`#include <SecurityHandler.h>`

Inheritance diagram for pdftron::SDF::SecurityHandler:

## 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 , e_AES_256 }
enum | OverloadedFunction { 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
bool | IsValid () const
void | SetModified (bool is_modified=true)
| SecurityHandler (AlgorithmType crypt_type)
| SecurityHandler (const char *name, int key_len, int enc_code)
| SecurityHandler ()
| SecurityHandler (const SecurityHandler &s)
SecurityHandler & | operator= (const SecurityHandler &)
virtual | ~SecurityHandler ()
void | ChangeUserPasswordASCII (const char *password)
void | ChangeUserPassword (const char *password, size_t pwd_length)
void | ChangeUserPassword (const pdftron::UString &password)
void | ChangeUserPassword (const std::vector< pdftron::UInt8 > &password_buf)
const char * | GetUserPassword ()
size_t | GetUserPasswordSize () const
void | ChangeMasterPasswordASCII (const char *password)
void | ChangeMasterPassword (const char *password, size_t pwd_length)
void | ChangeMasterPassword (const pdftron::UString &password)
void | ChangeMasterPassword (const std::vector< pdftron::UInt8 > &password_buf)
const char * | GetMasterPassword ()
size_t | GetMasterPasswordSize () const
void | SetPermission (Permission perm, bool value)
void | ChangeRevisionNumber (int rev_num)
void | SetEncryptMetadata (bool encrypt_metadata)
int | GetRevisionNumber ()
bool | IsUserPasswordRequired ()
bool | IsMasterPasswordRequired ()
bool | IsAES () const
bool | IsAES (Obj stream) const
bool | IsRC4 () const
| operator bool ()
virtual void | AuthorizeFailed ()
virtual bool | Authorize (Permission p)
virtual bool | GetAuthorizationData (Permission req_opr)
virtual bool | EditSecurityData (SDFDoc &doc)
virtual Obj | FillEncryptDict (class SDFDoc &doc)
virtual SecurityHandler * | Clone (TRN_SecurityHandler base) const
void | InitPasswordASCII (const char *password)
void | InitPassword (const char *password, size_t pwd_length)
void | InitPassword (const pdftron::UString &password)
void | InitPassword (const std::vector< pdftron::UInt8 > &password_buf)
void | SetDerived (UInt32 overloaded_funct)
SecurityHandler * | GetDerived () const

## Detailed Description

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

Definition at line 22 of file SecurityHandler.h.

## Member Enumeration Documentation

## ◆ AlgorithmType

enum pdftron::SDF::SecurityHandler::AlgorithmType

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.
e_AES_256 | Use Crypt filters with 256-bit AES (Advanced Encryption Standard) algorithm.

Definition at line 101 of file SecurityHandler.h.

## ◆ OverloadedFunction

enum pdftron::SDF::SecurityHandler::OverloadedFunction

Enumerator
has_CloneProc |
has_AuthProc |
has_AuthFailedProc |
has_GetAuthDataProc |
has_EditSecurDataProc |
has_FillEncDictProc |

Definition at line 405 of file SecurityHandler.h.

## ◆ Permission

enum pdftron::SDF::SecurityHandler::Permission

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

Definition at line 26 of file SecurityHandler.h.

## Constructor & Destructor Documentation

## ◆ SecurityHandler() [1/4]

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

Create a Standard Security Handler.

Parameters

  crypt_type | The encryption algorithm identifier.

## ◆ SecurityHandler() [2/4]

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

Create a Standard Security Handler.

Parameters

  name | The name of the Standard Security Handler.
  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.

@default values for key_len and enc_code are 128 and 2 respectively.

## ◆ SecurityHandler() [3/4]

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

## ◆ SecurityHandler() [4/4]

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

## ◆ ~SecurityHandler()

virtual pdftron::SDF::SecurityHandler::~SecurityHandler | ( |  | ) |
| virtual

## Member Function Documentation

## ◆ Authorize()

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

## ◆ AuthorizeFailed()

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.

## ◆ ChangeMasterPassword() [1/3]

void pdftron::SDF::SecurityHandler::ChangeMasterPassword | ( | const char * | password,
|  | size_t | pwd_length )

Set the new master password to a binary string

Parameters

  password | the new user password

Remarks
  Deprecated. Use versions that accepts UString or buffer instead.

## ◆ ChangeMasterPassword() [2/3]

void pdftron::SDF::SecurityHandler::ChangeMasterPassword | ( | const pdftron::UString & | password | ) |

Sets the new master/owner password.

Parameters

  password | The new master/owner password.

## ◆ ChangeMasterPassword() [3/3]

void pdftron::SDF::SecurityHandler::ChangeMasterPassword | ( | const std::vector< pdftron::UInt8 > & | password_buf | ) |

Sets the new master/owner password.

Parameters

  password_buf | The new master/owner password.

## ◆ ChangeMasterPasswordASCII()

void pdftron::SDF::SecurityHandler::ChangeMasterPasswordASCII | ( | const char * | password | ) |

Set the new master password to an ASCII text string

Parameters

  password | the new master/owner password

Remarks
  Deprecated. Use versions that accepts UString or buffer instead.

## ◆ ChangeRevisionNumber()

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.

## ◆ ChangeUserPassword() [1/3]

void pdftron::SDF::SecurityHandler::ChangeUserPassword | ( | const char * | password,
|  | size_t | pwd_length )

Set the new user password to a binary string

Parameters

  password | the new user password

Remarks
  Deprecated. Use versions that accepts UString or buffer instead.

## ◆ ChangeUserPassword() [2/3]

void pdftron::SDF::SecurityHandler::ChangeUserPassword | ( | const pdftron::UString & | password | ) |

Sets the new user password.

Parameters

  password | The new user password.

## ◆ ChangeUserPassword() [3/3]

void pdftron::SDF::SecurityHandler::ChangeUserPassword | ( | const std::vector< pdftron::UInt8 > & | password_buf | ) |

Sets the new user password.

Parameters

  password_buf | The new user password.

## ◆ ChangeUserPasswordASCII()

void pdftron::SDF::SecurityHandler::ChangeUserPasswordASCII | ( | const char * | password | ) |

Set the new user password to an ASCII text string

Parameters

  password | the new user password

Remarks
  Deprecated. Use versions that accepts UString or buffer instead..

## ◆ Clone()

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.

## ◆ EditSecurityData()

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.

## ◆ FillEncryptDict()

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.

## ◆ GetAuthorizationData()

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.

## ◆ GetDerived()

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

Returns
  The derived class or NULL for standard security handler.

## ◆ GetEncryptionAlgorithmID()

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.

## ◆ GetHandlerDocName()

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.

## ◆ GetKeyLength()

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

Returns
  The length of the encryption key in bytes.

Note
  The returned key length is given in bytes.

## ◆ GetMasterPassword()

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

Returns
  Current master (owner) password.

## ◆ GetMasterPasswordSize()

size_t pdftron::SDF::SecurityHandler::GetMasterPasswordSize | ( |  | ) | const

Returns
  Length of the current owner password string. This has to be used when password is a non-ASCII string that may contain '\0' bytes.

## ◆ GetPermission()

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.

## ◆ GetRevisionNumber()

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

Returns
  the revision number of the standard security algorithm.

## ◆ GetUserPassword()

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

Returns
  Current user password.

## ◆ GetUserPasswordSize()

size_t pdftron::SDF::SecurityHandler::GetUserPasswordSize | ( |  | ) | const

Returns
  Length of the current user password string. This has to be used when password is a non-ASCII string that may contain '\0' bytes.

## ◆ InitPassword() [1/3]

void pdftron::SDF::SecurityHandler::InitPassword | ( | const char * | password,
|  | size_t | pwd_length )

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

Remarks
  Deprecated. Use versions that accepts UString or buffer instead.

## ◆ InitPassword() [2/3]

void pdftron::SDF::SecurityHandler::InitPassword | ( | const pdftron::UString & | password | ) |

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

## ◆ InitPassword() [3/3]

void pdftron::SDF::SecurityHandler::InitPassword | ( | const std::vector< pdftron::UInt8 > & | password_buf | ) |

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

## ◆ InitPasswordASCII()

void pdftron::SDF::SecurityHandler::InitPasswordASCII | ( | const char * | password | ) |

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

Remarks
  Deprecated. Use versions that accepts UString or buffer instead.

## ◆ IsAES() [1/2]

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.

## ◆ IsAES() [2/2]

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

## ◆ IsMasterPasswordRequired()

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

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

## ◆ IsModified()

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.

## ◆ IsRC4()

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

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

## ◆ IsUserPasswordRequired()

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

Returns
  true if the SecurityHandler requires a user password.

## ◆ IsValid()

bool pdftron::SDF::SecurityHandler::IsValid | ( |  | ) | const

Returns
  - true if the SecurityHandler is valid.

## ◆ operator bool()

pdftron::SDF::SecurityHandler::operator bool | ( |  | ) |
| inline

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

Definition at line 299 of file SecurityHandler.h.

## ◆ operator=()

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

## ◆ SetDerived()

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);

## ◆ SetEncryptMetadata()

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.

## ◆ SetModified()

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

Parameters

  is_modified | Value to set the SecurityHandler's is modified flag to

## ◆ SetPermission()

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.

The documentation for this class was generated from the following file:

- SDF/SecurityHandler.h