Class SecurityHandler

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

Inheritance

object

SecurityHandler

PDFTronCustomSecurityHandler

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: pdftron.SDF

Assembly: PDFTronDotNet.dll

Syntax

public class SecurityHandler : IDisposable

Constructors

SecurityHandler()

Declaration

public SecurityHandler()

SecurityHandler(int, int, string)

Creates a standard security handler

Declaration

public SecurityHandler(int key_len, int enc_code, string name)

Parameters

Type	Name	Description
int	key_len	The bit length of the encryption key (40 or 128 bit).
int	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): Encryption using 40-bit RC4 algorithm. Encryption using 128-bit RC4 algorithm. Available in PDF 1.4 and above. This algorithm was deprecated by PDF standard and is not supported. Encryption using Crypt filters and 128-bit AES (Advanced Encryption Standard) algorithm. Available in PDF 1.6 and above.
string	name	name of the security handler

Type

Name

Description

int

key_len

The bit length of the encryption key (40 or 128 bit).

int

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

Encryption using 40-bit RC4 algorithm.
Encryption using 128-bit RC4 algorithm. Available in PDF 1.4 and above.
This algorithm was deprecated by PDF standard and is not supported.
Encryption using Crypt filters and 128-bit AES (Advanced Encryption Standard) algorithm. Available in PDF 1.6 and above.

string

name

name of the security handler

SecurityHandler(SecurityHandler)

Create a standard security handler from a given handler

Declaration

public SecurityHandler(SecurityHandler s)

Parameters

Type	Name	Description
SecurityHandler	s	a SecurityHandler instance

SecurityHandler(AlgorithmType)

Declaration

public SecurityHandler(SecurityHandler.AlgorithmType type)

Parameters

Type	Name	Description
SecurityHandler.AlgorithmType	type

Methods

Authorize(Permission)

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.

Declaration

public bool Authorize(SecurityHandler.Permission req_opr)

Parameters

Type	Name	Description
SecurityHandler.Permission	req_opr	permission to authorize

Returns

Type	Description
bool

Remarks

This callback must not obtain the authorization data 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.

AuthorizeFailed()

A callback method indicating repeated failed authorization. this callback in order to provide a UI feedback for failed authorization. Default implementation returns immediately.

Declaration

public void AuthorizeFailed()

ChangeMasterPassword(string)

Changes master password

Declaration

public void ChangeMasterPassword(string password)

Parameters

Type	Name	Description
string	password	new master password

ChangeRevisionNumber(int)

Changes revision number

Declaration

public void ChangeRevisionNumber(int rev_num)

Parameters

Type	Name	Description
int	rev_num	new revision number

ChangeUserPassword(string)

Changes user password

Declaration

public void ChangeUserPassword(string password)

Parameters

Type	Name	Description
string	password	new password

Clone()

Clones instance of SecurityHandler.

Declaration

public SecurityHandler Clone()

Returns

Type	Description
SecurityHandler	A new, cloned instance of SecurityHandler.

Remarks

this method must be implemented in any derived class from SecurityHandler.

Destroy()

Declaration

public void Destroy()

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration

public void Dispose()

Dispose(bool)

Declaration

protected virtual void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing

EditSecurityData(SDFDoc)

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

Declaration

public bool EditSecurityData(SDFDoc doc)

Parameters

Type	Name	Description
SDFDoc	doc	document to change security data

Returns

Type	Description
bool	true if the operation was successful false otherwise.

FillEncryptDict(SDFDoc)

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.

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

Declaration

public Obj FillEncryptDict(SDFDoc doc)

Parameters

Type	Name	Description
SDFDoc	doc	The document to save.

Returns

Type	Description
Obj	encrypt_dict

~SecurityHandler()

Declaration

protected ~SecurityHandler()

GetAuthorizationData(Permission)

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.

Declaration

public bool GetAuthorizationData(SecurityHandler.Permission req_opr)

Parameters

Type	Name	Description
SecurityHandler.Permission	req_opr	the permission for which authorization data is requested.

Returns

Type	Description
bool	false if the operation was canceled, true otherwise.

GetEncryptionAlgorithmID()

Gets encryption algorithm

Declaration

public int GetEncryptionAlgorithmID()

Returns

Type	Description
int	encryption algorithm

GetHandlerDocName()

Gets the handler doc name.

Declaration

public string GetHandlerDocName()

Returns

Type	Description
string	The name of the security handler as it appears in the serialized file as the value of /Filter key in /Encrypt dictionary.

GetKeyLength()

Gets key length

Declaration

public int GetKeyLength()

Returns

Type	Description
int	length of the encryption key

GetMasterPassword()

Gets master password

Declaration

public string GetMasterPassword()

Returns

Type	Description
string	master password

GetPermission(Permission)

Gets permission

Declaration

public bool GetPermission(SecurityHandler.Permission p)

Parameters

Type	Name	Description
SecurityHandler.Permission	p	A Permission to be granted.

Returns

Type	Description
bool	true if the SecurityHandler permits the specified action `p` on the document, or false if the permission was not granted

Remarks

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

Gets revision number

Declaration

public int GetRevisionNumber()

Returns

Type	Description
int	revsion number

GetUserPassword()

Gets user password

Declaration

public string GetUserPassword()

Returns

Type	Description
string	user password

InitPassword(string)

Initializes password

Declaration

public void InitPassword(string password)

Parameters

Type	Name	Description
string	password	initial password

IsAES()

Checks if AES encryption algorithm is used

Declaration

public bool IsAES()

Returns

Type	Description
bool	true, if AES is used, false otherwise

IsAES(Obj)

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

Declaration

public bool IsAES(Obj stream)

Parameters

Type	Name	Description
Obj	stream	A pointer to an `SDF::Stream` object

Returns

Type	Description
bool	true if the given stream is encrypted using AES encryption.

IsMasterPasswordRequired()

Checks if master password required

Declaration

public bool IsMasterPasswordRequired()

Returns

Type	Description
bool	true if master password is required, false otherwise

IsModified()

Checks if security handler is modified

Declaration

public bool IsModified()

Returns

Type	Description
bool	true if security handler is modified, false otherwise

IsRC4()

Checks if RC4 encryption algorithm is used

Declaration

public bool IsRC4()

Returns

Type	Description
bool	true, if RC4 is used, false otherwise

IsUserPasswordRequired()

Checks if user password required

Declaration

public bool IsUserPasswordRequired()

Returns

Type	Description
bool	true if user password required, false otherwise

SetEncryptMetadata(bool)

Sets whether to encrypt metadata

Declaration

public void SetEncryptMetadata(bool encrypt_metadata)

Parameters

Type	Name	Description
bool	encrypt_metadata	whether to encrypt metadata

SetModified()

Sets if security handler is modified

Declaration

public void SetModified()

SetModified(bool)

Sets if security handler is modified

Declaration

public void SetModified(bool is_modified)

Parameters

Type	Name	Description
bool	is_modified	true if the security handler is modified

SetPermission(Permission, bool)

Set the permission setting of the StdSecurityHandler.

Declaration

public void SetPermission(SecurityHandler.Permission perm, bool value)

Parameters

Type Name Description

Type	Name	Description
SecurityHandler.Permission	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.`
bool	value	true if the permission/s should be granted, false otherwise.

SecurityHandler.Permission

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.

bool

value

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

Implements

IDisposable