PSPDFDocumentSecurityOptions

Objective-C


@interface PSPDFDocumentSecurityOptions : NSObject

Swift

class SecurityOptions : NSObject

This class describes the security options you want to use when saving a PDF file. Using a security options object overrides the default options of a file.

A PDF file can have multiple security-related options set. The owner password generally controls the editing of a document and is required as soon as you want to encrypt a document of any kind. The user password prevents users from viewing the PDF. It is optional but if you specify it you also need to specify an owner password.

You can also specify the key length of the encryption. This controls how large the key is that is used for actually encrypting the document. The key is derived from the passwords you specify. As soon as you specify at least an owner password you also need to decide on a key length to be used. You can also specify PSPDFDocumentSecurityOptionsKeyLengthAutomatic in all cases and let PSPDFKit decide on if and what key length to use.

To specify what operations are allowed when opening the document with user privileges you can also set PSPDFDocumentPermissions. With user privileges you can always view the file in question and by specifying PSPDFDocumentPermissions you can grant further rights that otherwise would only be available when the user has owner privileges.

PSPDFKit supports two encryption algorithms: RC4 and AES. RC4 is a proprietary encryption algorithm of RSA Security Inc. It is a symmetric stream cipher, ie. the same algorithm is used for both encryption and decryption, and the algorithm does not change the length of the data. AES support was introduced with PDF 1.6. It is a symmetric block cipher, ie. the same algorithm is used for both encryption and decryption, and the length of the data when encrypted is rounded up to a multiple of the block size, which is fixed in this implementation to always be 16 bytes.

Note

In order to use this class, you need a license that enables you to use the Document Editor. If you want to process a file while keeping the options of the original file, simply pass nil for security options.
  • Initializes a newly allocated document security options object with no passwords. Use this instance to save a document without any security. This is a convenience initializer and is equivalent to sending initWithOwnerPassword:userPassword: with both passwords set to nil.

    Declaration

    Objective-C

    - (nonnull instancetype)init;

    Swift

    convenience init()
  • Allows you to set different passwords on the resulting document. This is a convenience initializer and is equivalent to sending initWithOwnerPassword:userPassword:keyLength: with keyLength set to PSPDFDocumentSecurityOptionsKeyLengthAutomatic.

    If an error occurs, this returns nil and throws the error (Swift) or sets the out error parameter to the encountered error (Objective-C).

    Declaration

    Objective-C

    - (nullable instancetype)
        initWithOwnerPassword:(nullable NSString *)ownerPassword
                 userPassword:(nullable NSString *)userPassword
                        error:(NSError *_Nullable *_Nullable)error;

    Swift

    convenience init(ownerPassword: String?, userPassword: String?) throws

    Parameters

    ownerPassword

    The password to be used as the document owner password.

    userPassword

    The password to be used as the password of a regular user.

    error

    Upon return contains an error if the creation was not possible.

  • Allows you to set different passwords on the resulting document.

    If an error occurs, this returns nil and throws the error (Swift) or sets the out error parameter to the encountered error (Objective-C).

    Declaration

    Objective-C

    - (nullable instancetype)
        initWithOwnerPassword:(nullable NSString *)ownerPassword
                 userPassword:(nullable NSString *)userPassword
                    keyLength:(NSUInteger)keyLength
                        error:(NSError *_Nullable *_Nullable)error;

    Swift

    convenience init(ownerPassword: String?, userPassword: String?, keyLength: UInt) throws

    Parameters

    ownerPassword

    The password to be used as the document owner password.

    userPassword

    The password to be used as the password of a regular user.

    keyLength

    The length of the crypto key. This key must be a multiple of 8 and between 40 and 128. You can also set the length to PSPDFDocumentSecurityOptionsKeyLengthAutomatic to let PSPDFKit maintain the key length for you. If you do not have special needs, this might be the best choice for both, encrypted and unencrypted documents.

    error

    Upon return contains an error if the creation was not possible.

  • Allows you to set different passwords on the resulting document.

    If an error occurs, this returns nil and throws the error (Swift) or sets the out error parameter to the encountered error (Objective-C).

    Declaration

    Objective-C

    - (nullable instancetype)
        initWithOwnerPassword:(nullable NSString *)ownerPassword
                 userPassword:(nullable NSString *)userPassword
                    keyLength:(NSUInteger)keyLength
                  permissions:(PSPDFDocumentPermissions)documentPermissions
                        error:(NSError *_Nullable *_Nullable)error;

    Swift

    convenience init(ownerPassword: String?, userPassword: String?, keyLength: UInt, permissions documentPermissions: DocumentPermissions) throws

    Parameters

    ownerPassword

    The password to be used as the document owner password.

    userPassword

    The password to be used as the password of a regular user.

    keyLength

    The length of the crypto key. This key must be a multiple of 8 and between 40 and 128. You can also set the length to PSPDFDocumentSecurityOptionsKeyLengthAutomatic to let PSPDFKit maintain the key length for you. If you do not have special needs, this might be the best choice for both, encrypted and unencrypted documents.

    documentPermissions

    The permissions that should be set on the document.

    error

    Upon return contains an error if the creation was not possible.

  • Allows you to set different passwords on the resulting document.

    If an error occurs, this returns nil and throws the error (Swift) or sets the out error parameter to the encountered error (Objective-C).

    Declaration

    Objective-C

    - (nullable instancetype)
        initWithOwnerPassword:(nullable NSString *)ownerPassword
                 userPassword:(nullable NSString *)userPassword
                    keyLength:(NSUInteger)keyLength
                  permissions:(PSPDFDocumentPermissions)documentPermissions
          encryptionAlgorithm:(PSPDFDocumentEncryptionAlgorithm)encryptionAlgorithm
                        error:(NSError *_Nullable *_Nullable)error;

    Swift

    init(ownerPassword: String?, userPassword: String?, keyLength: UInt, permissions documentPermissions: DocumentPermissions, encryptionAlgorithm: DocumentEncryptionAlgorithm) throws

    Parameters

    ownerPassword

    The password to be used as the document owner password.

    userPassword

    The password to be used as the password of a regular user.

    keyLength

    The length of the crypto key. This key must be a multiple of 8 and between 40 and 128. You can also set the length to PSPDFDocumentSecurityOptionsKeyLengthAutomatic to let PSPDFKit maintain the key length for you. If you do not have special needs, this might be the best choice for both, encrypted and unencrypted documents.

    documentPermissions

    The permissions that should be set on the document.

    encryptionAlgorithm

    The encryption algorithm to use. Can be RC4 or AES (recommended).

    error

    Upon return contains an error if the creation was not possible.

  • The owner password that will be set in the processed document or nil if the password should be removed.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSString *ownerPassword;

    Swift

    var ownerPassword: String? { get }
  • The user password that will be set in the processed document or nil if the password should be removed.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSString *userPassword;

    Swift

    var userPassword: String? { get }
  • The key-length of the encryption.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSUInteger keyLength;

    Swift

    var keyLength: UInt { get }
  • The PSPDFDocumentPermissions that will be set.

    Declaration

    Objective-C

    @property (nonatomic, readonly) PSPDFDocumentPermissions permissions;

    Swift

    var permissions: DocumentPermissions { get }
  • The algorithm used to encrypt the document.

    Declaration

    Objective-C

    @property (nonatomic, readonly) PSPDFDocumentEncryptionAlgorithm encryptionAlgorithm;

    Swift

    var encryptionAlgorithm: DocumentEncryptionAlgorithm { get }