Show / Hide Table of Contents

# Class SecurityHandler

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

##### Inheritance

object
SecurityHandler
StdSecurityHandler

##### Implements

IDisposable

##### Inherited Members

object.ToString()
object.Equals(object)
object.Equals(object, object)
object.ReferenceEquals(object, object)
object.GetHashCode()
object.GetType()
object.MemberwiseClone()

###### Namespace: pdftron.SDF

###### Assembly: PDFNet.dll

##### Syntax

    public abstract class SecurityHandler : IDisposable

### Constructors

#### 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

#### SecurityHandler(SecurityHandler)

##### Declaration

    public SecurityHandler(SecurityHandler s)

##### Parameters

Type | Name | Description
--- | --- | ---
SecurityHandler | s |

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

##### Parameters

Type | Name | Description
--- | --- | ---
SecurityHandler.Permission | p | 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. 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(bool)

##### Declaration

    [HandleProcessCorruptedStateExceptions]
    protected virtual void Dispose(bool A_0)

##### Parameters

Type | Name | Description
--- | --- | ---
bool | 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
--- | ---
bool | 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.

#### ~SecurityHandler()

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

##### 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 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
--- | ---
bool | false if the operation was canceled, true otherwise.

#### GetEncryptionAlgorithmID()

Gets the encryption algorithm id.

##### Declaration

    public abstract int GetEncryptionAlgorithmID()

##### Returns

Type | Description
--- | ---
int | 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
--- | ---
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
--- | ---
int | The length of the encryption key in bytes.

##### Remarks

The returned key length is given in bytes.

#### GetPermission(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
--- | ---
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.

#### Initialize(SDFDoc, Obj, int)

##### Declaration

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

##### Parameters

Type | Name | Description
--- | --- | ---
SDFDoc | doc |
Obj | encrypt_dict |
int | 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
--- | ---
bool | 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(bool)

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
--- | --- | ---
bool | is_modified | new is_modified flag

### Implements

IDisposable