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 passnil
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 tonil
.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:
withkeyLength
set toPSPDFDocumentSecurityOptionsKeyLengthAutomatic
.If an error occurs, this returns
nil
and throws the error (Swift) or sets the outerror
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 outerror
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 outerror
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 outerror
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 }