PSPDFDocumentSecurityOptions

Objective-C


@interface PSPDFDocumentSecurityOptions : 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.

-init
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;
Return Value

A newly initialized instance of the receiver.


                      
                      
                      
                      
                      -initWithOwnerPassword:userPassword:error:

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.

Declaration

Objective-C

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

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.

Return Value

A newly initialized instance of the receiver. If an error occurs, this method returns nil while setting the out error parameter to the encountered error.


                      
                      
                      
                      
                      -initWithOwnerPassword:userPassword:keyLength:error:

Allows you to set different passwords on the resulting document.

Declaration

Objective-C

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

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

Return Value

A newly initialized instance of the receiver. If an error occurs, this method returns nil while setting the out error parameter to the encountered error.


                      
                      
                      
                      
                      -initWithOwnerPassword:userPassword:keyLength:permissions:error:

Allows you to set different passwords on the resulting document.

Declaration

Objective-C

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

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

Return Value

A newly initialized instance of the receiver. If an error occurs, this method returns nil while setting the out error parameter to the encountered error.


                      
                      
                      
                      
                      -initWithOwnerPassword:userPassword:keyLength:permissions:encryptionAlgorithm:error:

Allows you to set different passwords on the resulting document.

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;

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

Return Value

A newly initialized instance of the receiver. If an error occurs, this method returns nil while setting the out error parameter to the encountered error.

ownerPassword
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;
userPassword
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;
keyLength
The key-length of the encryption.
Declaration
Objective-C

@property (nonatomic, readonly) NSUInteger keyLength;
permissions
The PSPDFDocumentPermissions that will be set.
Declaration
Objective-C

@property (nonatomic, readonly) PSPDFDocumentPermissions permissions;


                      
                      
                      
                      
                      encryptionAlgorithm

The algorithm used to encrypt the document.

Declaration

Objective-C

@property (nonatomic, readonly) PSPDFDocumentEncryptionAlgorithm encryptionAlgorithm;