PTSecurityHandler

@interface PTSecurityHandler : NSObject

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

  • 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.

    Declaration

    Objective-C

    - (BOOL)GetPermission:(PTPermission)p;

    Swift

    func getPermission(_ p: PTPermission) -> Bool

    Parameters

    p

    A Permission to be granted.

    Return Value

    true if the SecurityHandler permits the specified action (Permission p) on the document, or false if the permission was not granted.

  • Note

    The returned key length is given in bytes.

    Declaration

    Objective-C

    - (int)GetKeyLength;

    Swift

    func getKeyLength() -> Int32

    Return Value

    The length of the encryption key in bytes.

  • Declaration

    Objective-C

    - (int)GetEncryptionAlgorithmID;

    Swift

    func getEncryptionAlgorithmID() -> Int32

    Return Value

    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.

  • Declaration

    Objective-C

    - (NSString *)GetHandlerDocName;

    Swift

    func getDocName() -> String!

    Return Value

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

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

    Declaration

    Objective-C

    - (BOOL)IsModified;

    Swift

    func isModified() -> Bool

    Return Value

    - true if the SecurityHandler was modified (by calling SetModified()) or false otherwise.

  • Declaration

    Objective-C

    - (BOOL)IsValid;

    Swift

    func isValid() -> Bool

    Return Value

    - true if the SecurityHandler is valid.

  • 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

    Objective-C

    - (void)SetModified:(BOOL)is_modified;

    Swift

    func setModified(_ is_modified: Bool)

    Parameters

    is_modified

    Value to set the SecurityHandler’s is modified flag to

  • Create a Standard Security Handler.

    Declaration

    Objective-C

    - (instancetype)initWithCrypt_type:(PTAlgorithmType)crypt_type;

    Swift

    init!(crypt_type: PTAlgorithmType)

    Parameters

    crypt_type

    The encryption algorithm identifier.

  • Undocumented

    Declaration

    Objective-C

    - (instancetype)initWithName: (NSString *)name key_len:  (int)key_len enc_code:  (int)enc_code;

    Swift

    init!(name: String!, key_len: Int32, enc_code: Int32)

  • Undocumented

    Declaration

    Objective-C

    - (instancetype)init;

    Swift

    init!()

  • Set the new user password to an ASCII text string

    @remark Deprecated. Use versions that accepts UString or buffer instead..

    Declaration

    Objective-C

    - (void)ChangeUserPasswordASCII:(NSString *)password;

    Swift

    func changeUserPasswordASCII(_ password: String!)

    Parameters

    password

    the new user password

  • Set the new user password to a binary string

    @remark Deprecated. Use versions that accepts UString or buffer instead.

    Declaration

    Objective-C

    - (void)ChangeUserPasswordWithLength:(NSString *)password
                          pwd_length:(unsigned long)pwd_length;

    Swift

    func changeUserPassword(withLength password: String!, pwd_length: UInt)

    Parameters

    password

    the new user password

  • Sets the new user password.

    Declaration

    Objective-C

    - (void)ChangeUserPassword:(NSString *)password;

    Swift

    func changeUserPassword(_ password: String!)

    Parameters

    password

    The new user password.

  • Declaration

    Objective-C

    - (NSString *)GetUserPassword;

    Swift

    func getUserPassword() -> String!

    Return Value

    Current user password.

  • Declaration

    Objective-C

    - (unsigned long)GetUserPasswordSize;

    Swift

    func getUserPasswordSize() -> UInt

    Return Value

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

  • Set the new master password to an ASCII text string

    @remark Deprecated. Use versions that accepts UString or buffer instead.

    Declaration

    Objective-C

    - (void)ChangeMasterPasswordASCII:(NSString *)password;

    Swift

    func changeMasterPasswordASCII(_ password: String!)

    Parameters

    password

    the new master/owner password

  • Set the new master password to a binary string

    @remark Deprecated. Use versions that accepts UString or buffer instead.

    Declaration

    Objective-C

    - (void)ChangeMasterPasswordWithLength:(NSString *)password
                            pwd_length:(unsigned long)pwd_length;

    Swift

    func changeMasterPassword(withLength password: String!, pwd_length: UInt)

    Parameters

    password

    the new user password

  • Sets the new master/owner password.

    Declaration

    Objective-C

    - (void)ChangeMasterPassword:(NSString *)password;

    Swift

    func changeMasterPassword(_ password: String!)

    Parameters

    password

    The new master/owner password.

  • Declaration

    Objective-C

    - (NSString *)GetMasterPassword;

    Swift

    func getMasterPassword() -> String!

    Return Value

    Current master (owner) password.

  • Declaration

    Objective-C

    - (unsigned long)GetMasterPasswordSize;

    Swift

    func getMasterPasswordSize() -> UInt

    Return Value

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

  • Set the permission setting of the StdSecurityHandler.

    Declaration

    Objective-C

    - (void)SetPermission:(PTPermission)perm value:(BOOL)value;

    Swift

    func setPermission(_ perm: PTPermission, value: Bool)

    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.
    value

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

  • Change the revision number and the encryption algorithm of the standard security handler.

    Declaration

    Objective-C

    - (void)ChangeRevisionNumber:(int)rev_num;

    Swift

    func changeRevisionNumber(_ rev_num: Int32)

    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.

  • Indicates whether the document-level metadata stream is to be encrypted.

    Note

    EncryptMetadata flag affects only Crypt filters available in PDF 1.5 (Acrobat 6) and later. By default, metadata stream will be encrypted.

    Declaration

    Objective-C

    - (void)SetEncryptMetadata:(BOOL)encrypt_metadata;

    Swift

    func setEncryptMetadata(_ encrypt_metadata: Bool)

    Parameters

    encrypt_metadata

    true if metadata stream should be encrypted, false otherwise.

  • Declaration

    Objective-C

    - (int)GetRevisionNumber;

    Swift

    func getRevisionNumber() -> Int32

    Return Value

    the revision number of the standard security algorithm.

  • Declaration

    Objective-C

    - (BOOL)IsUserPasswordRequired;

    Swift

    func isUserPasswordRequired() -> Bool

    Return Value

    true if the SecurityHandler requires a user password.

  • Declaration

    Objective-C

    - (BOOL)IsMasterPasswordRequired;

    Swift

    func isMasterPasswordRequired() -> Bool

    Return Value

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

  • Declaration

    Objective-C

    - (BOOL)IsAES;

    Swift

    func isAES() -> Bool

    Return Value

    true is this security handler uses 128 bit AES (Advanced Encryption Standard) algorithm to encrypt strings or streams.

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

    Declaration

    Objective-C

    - (BOOL)IsAESWithStream:(PTObj *)stream;

    Swift

    func isAES(withStream stream: PTObj!) -> Bool

    Parameters

    stream

    A pointer to an SDF::Stream object

    Return Value

    true if the given stream is encrypted using AES encryption.

  • Declaration

    Objective-C

    - (BOOL)IsRC4;

    Swift

    func isRC4() -> Bool

    Return Value

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

  • 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

    Objective-C

    - (void)AuthorizeFailed;

    Swift

    func authorizeFailed()

  • 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.

    Declaration

    Objective-C

    - (BOOL)Authorize:(PTPermission)p;

    Swift

    func authorize(_ p: PTPermission) -> Bool

    Parameters

    p

    - permission to authorize

  • 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

    Objective-C

    - (BOOL)GetAuthorizationData:(PTPermission)req_opr;

    Swift

    func getAuthorizationData(_ req_opr: PTPermission) -> Bool

    Parameters

    req_opr

    - the permission for which authorization data is requested.

    Return Value

    false if the operation was canceled, true otherwise.

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

    Declaration

    Objective-C

    - (BOOL)EditSecurityData:(PTSDFDoc *)doc;

    Swift

    func editSecurityData(_ doc: PTSDFDoc!) -> Bool

    Return Value

    true if the operation was successful false otherwise.

  • 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

    Declaration

    Objective-C

    - (PTObj *)FillEncryptDict:(PTSDFDoc *)doc;

    Swift

    func fillEncryptDict(_ doc: PTSDFDoc!) -> PTObj!

    Parameters

    doc

    - The document to save.

    Return Value

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

  • Note

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

    Declaration

    Objective-C

    - (PTSecurityHandler *)Clone:(void *)base;

    Swift

    func clone(_ base: UnsafeMutableRawPointer!) -> PTSecurityHandler!

    Return Value

    A new, cloned instance of SecurityHandler.

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

    @remark Deprecated. Use versions that accepts UString or buffer instead.

    Declaration

    Objective-C

    - (void)InitPasswordASCII:(NSString *)password;

    Swift

    func initPasswordASCII(_ password: String!)

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

    @remark Deprecated. Use versions that accepts UString or buffer instead.

    Declaration

    Objective-C

    - (void)InitPasswordWithLength:(NSString *)password
                    pwd_length:(unsigned long)pwd_length;

    Swift

    func initPassword(withLength password: String!, pwd_length: UInt)

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

    Declaration

    Objective-C

    - (void)InitPassword:(NSString *)password;

    Swift

    func initPassword(_ password: String!)

  • 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.

    Declaration

    Objective-C

    - (void)SetDerived:(unsigned int)overloaded_funct;

    Swift

    func setDerived(_ overloaded_funct: UInt32)

    Parameters

    overloaded_funct

    A flag that specifies which functions are overloaded in the derived class. For example: SetDerived(SecurityHandler::has_Clone + SecurityHandler::has_FillEncDictProc);

  • Declaration

    Objective-C

    - (PTSecurityHandler *)GetDerived;

    Swift

    func getDerived() -> PTSecurityHandler!

    Return Value

    The derived class or NULL for standard security handler.