Class SecurityHandler

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

Inheritance

System.Object

SecurityHandler

StdSecurityHandler

Implements

System.IDisposable

Inherited Members

System.Object.ToString()

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

Namespace: pdftron.SDF

Assembly: PDFNet.dll

Syntax

public abstract class SecurityHandler : IDisposable

Constructors

SecurityHandler(SecurityHandler)

Declaration

public SecurityHandler(SecurityHandler s)

Parameters

Type	Name	Description
SecurityHandler	s

SecurityHandler(Int32, Int32, String)

Creates a standard security handler

Declaration

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

Parameters

Type	Name	Description
System.Int32	key_len	The bit length of the encryption key (40 or 128 bit).
System.Int32	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.
System.String	name	name of the security handler

Methods

Authorize(SecurityHandler.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 abstract bool Authorize(SecurityHandler.Permission p)

Parameters

Type	Name	Description
SecurityHandler.Permission	p	permission to authorize

Returns

Type	Description
System.Boolean

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. Override this callback in order to provide a UI feedback for failed authorization. Default implementation returns immediately.

Declaration

public abstract void AuthorizeFailed()

Clone()

Clones instance of SecurityHandler.

Declaration

public abstract SecurityHandler Clone()

Returns

Type	Description
SecurityHandler	A new, cloned instance of SecurityHandler.

Remarks

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

Dispose()

Releases all resources used by the SecurityHandler

Declaration

public override sealed void Dispose()

Dispose(Boolean)

Declaration

[HandleProcessCorruptedStateExceptions]
protected virtual void Dispose(bool A_0)

Parameters

Type	Name	Description
System.Boolean	A_0

EditSecurityData(SDFDoc)

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

Declaration

public abstract bool EditSecurityData(SDFDoc doc)

Parameters

Type	Name	Description
SDFDoc	doc	document to change security data

Returns

Type	Description
System.Boolean	true if the operation was successful false otherwise.

FillEncryptDict(SDFDoc)

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

Declaration

public abstract Obj FillEncryptDict(SDFDoc doc)

Parameters

Type	Name	Description
SDFDoc	doc	document to save

Returns

Type	Description
Obj	encrypted dictionary

Remarks

Called when an encrypted document is saved. 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.

Finalize()

Allows an SecurityHandler to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.

Declaration

protected void Finalize()

GetAuthorizationData(SecurityHandler.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 abstract 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
System.Boolean	false if the operation was canceled, true otherwise.

GetEncryptionAlgorithmID()

Gets the encryption algorithm id.

Declaration

public abstract int GetEncryptionAlgorithmID()

Returns

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

GetHandlerDocName()

Gets the handler doc name.

Declaration

public abstract string GetHandlerDocName()

Returns

Type	Description
System.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 the key length.

Declaration

public abstract int GetKeyLength()

Returns

Type	Description
System.Int32	The length of the encryption key in bytes.

Remarks

The returned key length is given in bytes.

GetPermission(SecurityHandler.Permission)

Gets permission

Declaration

public abstract bool GetPermission(SecurityHandler.Permission p)

Parameters

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

Returns

Type	Description
System.Boolean	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.

Initialize(SDFDoc, Obj, Int32)

Declaration

public abstract void Initialize(SDFDoc doc, Obj encrypt_dict, int custom_data)

Parameters

Type	Name	Description
SDFDoc	doc
Obj	encrypt_dict
System.Int32	custom_data

IsModified()

If the user changes SecurityHandler's settings (e.g. by changing a password), IsModified() should return true.

Declaration

public abstract bool IsModified()

Returns

Type	Description
System.Boolean	true if the SecurityHandler was modified (by calling SetModified()) or false otherwise.

SetModified()

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

Declaration

public abstract void SetModified()

SetModified(Boolean)

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

Declaration

public abstract void SetModified(bool is_modified)

Parameters

Type	Name	Description
System.Boolean	is_modified	new is_modified flag

Implements

System.IDisposable