pdftron::SDF::SecurityHandler Class Reference

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

#include <SecurityHandler.h>

List of all members.

Public Types
enum	Permission {   e_all = 1, e_doc_open, e_doc_secure, 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...
Public Member Functions
	SecurityHandler (TRN_SecurityHandler impl, bool owner)
bool	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.
SecurityHandler	Clone ()
	Returns: A new, cloned instance of SecurityHandler.
int	GetKeyLength () const
	Returns: The length of the encryption key in bytes.
int	GetEncryptionAlgorithmID () const
	Returns: The encryption algorithm identifier.
const char *	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	IsModified () const
	Returns: - true if the SecurityHandler was modified (by calling SetModified()) or false otherwise.
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 (int key_len, int enc_code)
	Create a Standard Security Handler.
	SecurityHandler ()
	SecurityHandler (const SecurityHandler &s)
	~SecurityHandler ()
void	ChangeUserPassword (const char *password)
	Modify the user password.
const char *	GetUserPassword ()
	Returns: Current user password.
void	ChangeMasterPassword (const char *password)
	Modify the master password.
const char *	GetMasterPassword ()
	Returns: Current master password.
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 ()
	Returns: the revision number of the standard security algorithm.
bool	IsUserPasswordRequired ()
	Returns: true if the SecurityHandler requires a user password.
bool	IsMasterPasswordRequired ()
	Returns: true if the SecurityHandler requires a master (owner) password.
bool	IsAES () const
	Returns: true is this security handler uses 128 bit AES (Advanced Encryption Standard) algorithm to encrypt strings or streams.
bool	IsAES (Obj stream) const
	The following function can be used to verify whether a given stream is encrypted using AES.
bool	IsRC4 () const
	Returns: true is this security handler uses RC4 algorithm to encrypt strings or streams.
	operator bool ()
	Returns: true if the object is not null, false otherwise.

---

Detailed Description

Standard Security Handler is a built-in password-based security handler.

---

Member Enumeration Documentation

enum pdftron::SDF::SecurityHandler::Permission

Enumerator:

e_all
e_doc_open	open and decrypt the document.
e_doc_secure	change the document’s security settings.
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

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.

---

Constructor & Destructor Documentation

pdftron::SDF::SecurityHandler::SecurityHandler	(	TRN_SecurityHandler	impl,
		bool	owner
	)

pdftron::SDF::SecurityHandler::SecurityHandler

(

AlgorithmType

crypt_type

)

Create a Standard Security Handler.

Parameters:

crypt_type

The encryption algorithm identifier.

pdftron::SDF::SecurityHandler::SecurityHandler	(	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

)

pdftron::SDF::SecurityHandler::~SecurityHandler

(

)

---

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.

SecurityHandler pdftron::SDF::SecurityHandler::Clone

(

)

Returns:

A new, cloned instance of SecurityHandler.

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

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_all // grant all permissions if true, or none if false 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.

---

© 2002-2008 PDFTron Systems Inc.