PDF Security

Definitions for pdf security related operation.
Definitions and functions in this module are included in fpdf_security_r.h and fpdf_security_w.h.
Module: PDFSecurity
License Identifier: PDFSecurity/All
Available License Right: Reading/Writing.
For License Right Reading, see fpdf_security_r.h.
For License Right Writing, see fpdf_security_w.h.
More...

Classes
struct	FSPDF_SECURITYHANDLER
	Structure for custom security handler. More...
struct	FSPDF_SECURITYHANDLER_CERT
	Structure for certificate security handler. More...
struct	FSPDF_SECURITYHANDLER_FDRM
	Structure for Foxit DRM security handler. More...

Functions
FS_RESULT	FSPDF_Security_RegisterHandler (const FSCRT_BSTR *filter, FSPDF_SECURITYHANDLER *securityHandler)
	Register a custom security handler to Foxit PDF SDK, enabling access to a PDF document which is protected by customized security handler. More...
FS_RESULT	FSPDF_Security_UnregisterHandler (const FSCRT_BSTR *filter)
	Unregister a customer security handler to Foxit PDF SDK. More...
FS_RESULT	FSPDF_Security_SetCertificateHandler (FSPDF_SECURITYHANDLER_CERT *certificateHandler)
	Set certificate security handler to Foxit PDF SDK. More...
FS_RESULT	FSPDF_Security_SetFoxitDRMHandler (FSPDF_SECURITYHANDLER_FDRM *foxitDRMHandler)
	Set Foxit DRM security handler to Foxit PDF SDK. More...
FS_RESULT	FSPDF_Security_CheckPassword (FSCRT_DOCUMENT document, const FSCRT_BSTR *password, FS_INT32 *passwordType)
	Detect type of password. More...
FS_RESULT	FSPDF_Security_VerifyFoxitDRMEncryptionParams (FSCRT_DOCUMENT document, FS_BOOL *verified)
	Verify encryption parameters in a PDF document. More...
FS_RESULT	FSPDF_Security_GetFoxitDRMEncryptionParamValue (FSCRT_DOCUMENT document, const FSCRT_BSTR *key, FSCRT_BSTR *str)
	Get string value of a key from encryption parameters used for Foxit DRM security. More...
FS_RESULT	FSPDF_Security_StartPasswordEncryption (FSCRT_DOCUMENT document, FS_DWORD userPermissions, const FSCRT_BSTR *userPassword, const FSCRT_BSTR *ownerPassword, FS_INT32 cipher, FS_INT32 keyLen, FS_BOOL encryptMetadata, FSCRT_FILE encryptedFile, FS_INT32 flag, FSCRT_PROGRESS *encryptProgress)
	Start standard password encryption on a PDF document. More...
FS_RESULT	FSPDF_Security_StartCustomEncryption (FSCRT_DOCUMENT document, const FSCRT_BSTR *filter, const FSCRT_BSTR *subFilter, const FSCRT_BSTR *encryptInfo, FSPDF_SECURITYHANDLER *securityHandler, FS_BOOL encryptMetadata, FSCRT_FILE encryptedFile, FS_INT32 flag, FSCRT_PROGRESS *encryptProgress)
	Start custom PDF Encryption, and the PDF document will be protected by non-standard security handler. More...
FS_RESULT	FSPDF_Security_StartCertificateEncryption (FSCRT_DOCUMENT document, const FSCRT_BSTR *envelopes, FS_INT32 count, FS_INT32 cipher, const FSCRT_BSTR *encryptKey, FS_BOOL encryptMetadata, FSCRT_FILE encryptedFile, FS_INT32 flag, FSCRT_PROGRESS *encryptProgress)
	Encrypt the PDF document by certificate. More...
FS_RESULT	FSPDF_Security_SetFoxitDRMEncryptionParamValue (FSCRT_DOCUMENT document, const FSCRT_BSTR *key, const FSCRT_BSTR *str)
	Set string value of a key as encryption parameter for Foxit DRM encryption. More...
FS_RESULT	FSPDF_Security_StartFoxitDRMEncryption (FSCRT_DOCUMENT document, const FSCRT_BSTR *subFilter, FS_BOOL isOwner, FS_DWORD userPermissions, FS_INT32 cipher, FS_INT32 keyLen, const FSCRT_BSTR *fileID, const FSCRT_BSTR *initialKey, FS_BOOL encryptMetadata, FSCRT_FILE encryptedFile, FS_INT32 flag, FSCRT_PROGRESS *encryptProgress)
	Start PDF document encryption by using Foxit DRM. More...
FS_RESULT	FSPDF_Security_StartRMSEncryption (FSCRT_DOCUMENT document, const FSCRT_BSTR *publishLicense, const FSCRT_BSTR *serverEulList, FS_INT32 listCount, FS_INT32 irmVersion, FS_BOOL encryptMetadata, FSCRT_FILE encryptedFile, FS_INT32 flag, FSCRT_PROGRESS *encryptProgress)
	Start PDF document encryption by using Microsoft RMS. More...

Detailed Description

Definitions for pdf security related operation.
Definitions and functions in this module are included in fpdf_security_r.h and fpdf_security_w.h.
Module: PDFSecurity
License Identifier: PDFSecurity/All
Available License Right: Reading/Writing.
For License Right Reading, see fpdf_security_r.h.
For License Right Writing, see fpdf_security_w.h.

This module contains following features:

• 1. Password security:
  • a. Encrypt a PDF file by standard password encryption algorithm.
  • b. PDF reference defines a standard password encryption algorithm. Function FSPDF_Security_StartPasswordEncryption is used to do password encryption, it provides a progressive process. To open a password-encrypted PDF file, pass password as parameter directly when call function FSPDF_Doc_StartLoad or FSPDF_Doc_StartReLoad.
  • c.
  • d. Reference: section 3.5.2 in PDF Reference 1.7 describes standard password encryption.
• 2. Customized security:
  • a. Register or unregister a customized security handler, encrypt a PDF file by using customized encryption algorithm.
  • b. Customized security handler is an extension according to PDF reference. To encrypt a PDF file, call function FSPDF_Security_StartCustomEncryption in a progressive process. To open customized encryption PDF files, user should call function FSPDF_Security_RegisterHandler to register the corresponding security handler at first.
  • c. Note: customized security is not a common solution, but it is very effective in most cases. Implementors should ensure thread safety in FSPDF_SECURITYHANDLER.
  • d. Reference: section 3.5 in PDF Reference 1.7 describes the definition of security handler.
• 3. Certificate security:
  • a. Set certificate security handler, encrypt a PDF file by using public-key technologies.
  • b. Certificate security handler uses the industry standard Public Key Cryptographic Standard Number 7 (PKCS#7) to encode recipient list, decryption key, and access permission information. In PDF, use X.509 public key certificate to represent a recipient.
  • c. Note: FSPDF_SECURITYHANDLER_CERT is used to open X.509 certificate and implementors should ensure thread safety.
  • d. Reference: section 3.5.3 in PDF Reference 1.7 describes technologies on certificate security.
• 4. Foxit DRM:
  • a. Set Foxit DRM security handler, verify encryption parameters in Foxit DRM files, get or set parameter values, and encrypt a PDF file by Foxit DRM.
  • b. Foxit DRM is a corporation-level standard security technologies. It provides more flexible security solutions. To open a PDF file encrypted by Foxit DRM, call function FSPDF_Security_VerifyFoxitDRMEncryptionParams to check whether the encryption parameters are valid or not. Call function FSPDF_Security_StartFoxitDRMEncryption to encrypt a Foxit DRM PDF file in a progressive process.
• 5. RMS security:
  • a. Register or unregister a RMS security handler, encrypt a PDF file by using RMS encryption algorithm.
  • b. RMS security handler is a special custom security handler, which is implemented by application, using AD RMS SDK. Before doing RMS encryption or decryption, function FSPDF_Security_RegisterHandler should be called first to register the corresponding security handler with specific filter. To encrypt a PDF file, call function FSPDF_Security_StartRMSEncryption in a progressive process.
  • c. Note: RMS encryption and decryption algorithm is usually based on AD RMS SDK, which should be implemented by application. Implementors should ensure thread safety in FSPDF_SECURITYHANDLER.
  • d. Reference: section 3.5 in PDF Reference 1.7 describes the definition of security handler, and related specifications about Microsoft RMS.

Function Documentation

FS_RESULT FSPDF_Security_CheckPassword	(	FSCRT_DOCUMENT	document,
		const FSCRT_BSTR *	password,
		FS_INT32 *	passwordType
	)

Detect type of password.

This function is only used for standard password decryption.

Parameters

[in]	document	Handle to a FSCRT_DOCUMENT object which is a PDF document object.
[in]	password	Pointer to a FSCRT_BSTR structure that specifies the byte string password.
[out]	passwordType	Pointer to a FS_INT32 object that receives the password type. It would be one of the following macro definitions: FSPDF_PASSWORDTYPE_INVALID FSPDF_PASSWORDTYPE_NOPASSWORD FSPDF_PASSWORDTYPE_USERPASSWORD FSPDF_PASSWORDTYPE_OWNERPASSWORD

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter document, password, or passwordType is NULL.
FSCRT_ERRCODE_INVALIDTYPE if parameter document is not a type of PDF document.
FSCRT_ERRCODE_UNRECOVERABLE if function finds an unrecoverable error internally.
FSCRT_ERRCODE_ERROR if the password cannot be checked because of any other reason.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term recoverable.
• document: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_Security_GetFoxitDRMEncryptionParamValue	(	FSCRT_DOCUMENT	document,
		const FSCRT_BSTR *	key,
		FSCRT_BSTR *	str
	)

Get string value of a key from encryption parameters used for Foxit DRM security.

Parameters

[in]	document	Handle to a FSCRT_DOCUMENT object which is a PDF document object.
[in]	key	Pointer to a FSCRT_BSTR structure to the key string specified which is to get. Caller can define private key name. The following are pre-defined key names: Issuer: issuer name. Creator: creator of this file. FileID: file ID. FlowCode: flow code for application control. Order: order number. User: user name. ServiceURL: service URL for remote server. Vender: vender name.
[out]	str	Pointer to a FSCRT_BSTR structure that receives the string data. User should call function FSCRT_BStr_Clear to free the memory if necessary.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter document, key, or str is NULL, or str is an empty string object.
FSCRT_ERRCODE_INVALIDLICENSE if the current license is not authorized or Foxit DRM security is not allowed.
FSCRT_ERRCODE_INVALIDTYPE if parameter document is not a type of PDF document, or document is not a Foxit DRM encrypted one.
FSCRT_ERRCODE_OUTOFMEMORY if there is not enough memory or if the memory access is wrong.
FSCRT_ERRCODE_ERROR if string value cannot be obtained because of any other reason.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term unrecoverable.
• document: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_Security_RegisterHandler	(	const FSCRT_BSTR *	filter,
		FSPDF_SECURITYHANDLER *	securityHandler
	)

Register a custom security handler to Foxit PDF SDK, enabling access to a PDF document which is protected by customized security handler.

This function is only used for custom encryption and decryption, and RMS encryption and decryption (Microsoft RMS).
If user wants to use custom or RMS security handler, this function must be called first before doing customer encryption or decryption.
Once no more custom or RMS encryption or decryption is needed, function FSPDF_Security_UnregisterHandler shoulde be called to unregister current customer security handler.

Parameters

[in]	filter	Pointer to FSCRT_BSTR structure that specifies security filter. Specially: For Microsoft RMS, this should be "MicrosoftIRMServices".
[in]	securityHandler	Pointer to a valid FSPDF_SECURITYHANDLER structure to register a security handler.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter filter, or securityHandler is NULL.
FSCRT_ERRCODE_INVALIDLICENSE if the current license is not authorized or custom security is not allowed.
FSCRT_ERRCODE_INVALIDMANAGER if Foxit PDF SDK manager is not initialized.
FSCRT_ERRCODE_INVALIDMODULE if PDF module is not initialized.
FSCRT_ERRCODE_HANDLER if any callback function in parameter securityHandler is NULL.
FSCRT_ERRCODE_OUTOFMEMORY if there is not enough memory or if the memory access is wrong.
FSCRT_ERRCODE_CONFLICT if parameter filter collides with an existing one.
FSCRT_ERRCODE_UNRECOVERABLE if function finds an unrecoverable error internally.
FSCRT_ERRCODE_ERROR if the handler cannot be registered because of any other reason.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_Security_SetCertificateHandler

(

FSPDF_SECURITYHANDLER_CERT *

certificateHandler

)

Set certificate security handler to Foxit PDF SDK.

This function is only used for certificate decryption.
Certificate handler provides a method to extract decryption key from envelope.

Parameters

[in]

certificateHandler

Pointer to a FSPDF_SECURITYHANDLER_CERT structure which is a certificate handler.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter certificateHandler is NULL.
FSCRT_ERRCODE_INVALIDLICENSE if the current license is not authorized or certificate security is not allowed.
FSCRT_ERRCODE_INVALIDMANAGER if Foxit PDF SDK manager is not initialized.
FSCRT_ERRCODE_INVALIDMODULE if PDF module is not initialized.
FSCRT_ERRCODE_HANDLER if any callback function in parameter certificateHandler is NULL.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_Security_SetFoxitDRMEncryptionParamValue	(	FSCRT_DOCUMENT	document,
		const FSCRT_BSTR *	key,
		const FSCRT_BSTR *	str
	)

Set string value of a key as encryption parameter for Foxit DRM encryption.

Parameters

[in]	document	Handle to a FSCRT_DOCUMENT object which is a PDF document object.
[in]	key	Pointer to a FSCRT_BSTR structure to the key string specified which is to set. Caller can define private key name. The following are pre-defined key names: Issuer: issuer name. Creator: creator of this file. FileID: file ID. FlowCode: flow code for application control. Order: order number. User: user name. ServiceURL: service URL for remote server. Vender: vender name.
[in]	str	Pointer to a FSCRT_BSTR structure which is the key string value. If str is NULL, key will be removed.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter document, or key is NULL.
FSCRT_ERRCODE_INVALIDLICENSE if the current license is not authorized or Foxit DRM security is not allowed.
FSCRT_ERRCODE_INVALIDTYPE if parameter document is not a type of PDF document.
FSCRT_ERRCODE_OUTOFMEMORY if there is not enough memory or if the memory access is wrong.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term unrecoverable.
• document: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_Security_SetFoxitDRMHandler

(

FSPDF_SECURITYHANDLER_FDRM *

foxitDRMHandler

)

Set Foxit DRM security handler to Foxit PDF SDK.

This function is only used for Foxit DRM decryption.
Foxit DRM handler provides a method to extract decryption parameters of Foxit DRM.

Parameters

[in]

foxitDRMHandler

Pointer to a FSPDF_SECURITYHANDLER_FDRM structure which is a Foxit DRM handler.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter foxitDRMHandler is NULL.
FSCRT_ERRCODE_INVALIDLICENSE if the current license is not authorized or Foxit DRM security is not allowed.
FSCRT_ERRCODE_INVALIDMANAGER if Foxit PDF SDK manager is not initialized.
FSCRT_ERRCODE_INVALIDMODULE if PDF module is not initialized.
FSCRT_ERRCODE_HANDLER if any callback function in parameter foxitDRMHandler is NULL.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_Security_StartCertificateEncryption	(	FSCRT_DOCUMENT	document,
		const FSCRT_BSTR *	envelopes,
		FS_INT32	count,
		FS_INT32	cipher,
		const FSCRT_BSTR *	encryptKey,
		FS_BOOL	encryptMetadata,
		FSCRT_FILE	encryptedFile,
		FS_INT32	flag,
		FSCRT_PROGRESS *	encryptProgress
	)

Encrypt the PDF document by certificate.

It will take a long time to encrypt a document with complex or large contents, so Foxit PDF SDK uses a progressive process to do this.
Caller should pass parameter encryptProgress to function FSCRT_Progress_Continue to continue encrypting in steps, and should call function FSCRT_Progress_Release to destroy parameter encryptProgress object if encrypting process is over. If caller wants to change the saved PDF file version, call function FSCRT_Progress_SetProperty to set "fileversion".

Parameters

[in]	document	Handle to a FSCRT_DOCUMENT object which is a PDF document object.
[in]	envelopes	Pointer to FSCRT_BSTR structure that specifies a certificate enveloper array.
[in]	count	The count of envelopes. This should be greater than zero.
[in]	cipher	Encryption algorithm. It should be one of the following macro definitions: FSCRT_CIPHER_AES FSCRT_CIPHER_RC4
[in]	encryptKey	Pointer to FSCRT_BSTR structure that specifies the key information to be got after envelops calculate. For FSCRT_CIPHER_AES, length of parameter encryptKey can only be 16 or 32. For FSCRT_CIPHER_RC4, length of parameter encryptKey should be in the range from 5 to 16, including 5 and 16.
[in]	encryptMetadata	A boolean used to indicates whether to encrypt the meta data or not.
[in]	encryptedFile	Handle to a FSCRT_FILE object used to save encrypted PDF file.
[in]	flag	An integer value to specify saving mode. Please refer to macro definitions FSPDF_SAVEFLAG_XXX and this can be one or a combination of these macros except FSPDF_SAVEFLAG_REMOVESECURITY, FSPDF_SAVEFLAG_INCREMENTONLY and FSPDF_SAVEFLAG_LINEARIZED.
[out]	encryptProgress	Pointer to a FSCRT_PROGRESS handle that receives a handle of progressive process.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if any of five parameters document, envelopes , encryptKey, encryptedFile, and encryptProgress is NULL, or parameter count is below 1 when parameter envelopes is valid, or parameter flag is invalid, or any other parameter is unexpected.
FSCRT_ERRCODE_INVALIDLICENSE if the current license is not authorized or certificate security is not allowed.
FSCRT_ERRCODE_UNRECOVERABLE if function finds an unrecoverable error internally.
FSCRT_ERRCODE_INVALIDTYPE if parameter document is not a type of PDF document.
FSCRT_ERRCODE_UNSUPPORTED if parameter cipher is not applicable.
FSCRT_ERRCODE_INVALIDMODULE if PDF module is not initialized.
FSCRT_ERRCODE_OUTOFMEMORY if there is not enough memory or if the memory access is wrong.
FSCRT_ERRCODE_ERROR if document cannot be encrypted because of any other reason.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Note

ParameterencryptedFile should have WRITE callback functions implemented in structure FSCRT_FILEHANDLER.
If data cannot be written into parameter encryptedFile, FSCRT_ERRCODE_ERROR will return on calling function FSCRT_Progress_Continue during the next steps.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term recoverable.
• document: this handle is long-term partially recoverable.
• encryptedFile: this handle is long-term recoverable.
• encryptProgress: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_Security_StartCustomEncryption	(	FSCRT_DOCUMENT	document,
		const FSCRT_BSTR *	filter,
		const FSCRT_BSTR *	subFilter,
		const FSCRT_BSTR *	encryptInfo,
		FSPDF_SECURITYHANDLER *	securityHandler,
		FS_BOOL	encryptMetadata,
		FSCRT_FILE	encryptedFile,
		FS_INT32	flag,
		FSCRT_PROGRESS *	encryptProgress
	)

Start custom PDF Encryption, and the PDF document will be protected by non-standard security handler.

It will take a long time to encrypt a document with complex or large contents, so Foxit PDF SDK uses a progressive process to do this.
Caller should pass parameter encryptProgress to function FSCRT_Progress_Continue to continue encrypting in steps, call function FSCRT_Progress_Release to destroy encryptProgress object if encrypting process is done. If caller wants to change the saved PDF file version, call function FSCRT_Progress_SetProperty to set "fileversion".

Parameters

[in]	document	Handle to a FSCRT_DOCUMENT object which is a PDF document object.
[in]	filter	Pointer to a FSCRT_BSTR structure to specify the filter of the custom security handler.
[in]	subFilter	Pointer to a FSCRT_BSTR structure to specify the subfilter of the custom security handler.
[in]	encryptInfo	Pointer to a FSCRT_BSTR structure to specify encryption information data.
[in]	securityHandler	Pointer to a FSPDF_SECURITYHANDLER structure which represents a custom security handler to update default appearance.
[in]	encryptMetadata	A boolean used to indicates whether to encrypt the meta data or not.
[in]	encryptedFile	Handle to a FSCRT_FILE object used to save encrypted PDF file.
[in]	flag	An integer value to specify saving mode. Please refer to macro definitions FSPDF_SAVEFLAG_XXX and this can be one or a combination of these macros except FSPDF_SAVEFLAG_REMOVESECURITY, FSPDF_SAVEFLAG_INCREMENTONLY and FSPDF_SAVEFLAG_LINEARIZED.
[out]	encryptProgress	Pointer to a FSCRT_PROGRESS handle that receives a handle of progressive process.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter document, filter, encryptedFile, or encryptProgress is NULL, or parameter flag is invalid.
FSCRT_ERRCODE_INVALIDLICENSE if the current license is not authorized or custom security is not allowed.
FSCRT_ERRCODE_HANDLER if parameter securityHandler is invalid FSCRT_ERRCODE_INVALIDTYPE if parameter document is not a type of PDF document.
FSCRT_ERRCODE_INVALIDMODULE if PDF module is not initialized.
FSCRT_ERRCODE_UNRECOVERABLE if function finds an unrecoverable error internally.
FSCRT_ERRCODE_OUTOFMEMORY if there is not enough memory or if the memory access is wrong.
FSCRT_ERRCODE_ERROR if document cannot be encrypted because of any other reason.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Note

ParameterencryptedFile should have WRITE callback functions implemented in structure FSCRT_FILEHANDLER.
If data cannot be written into parameter encryptedFile, FSCRT_ERRCODE_ERROR will return on calling function FSCRT_Progress_Continue during the next steps.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term recoverable.
• document: this handle is long-term partially recoverable.
• encryptedFile: this handle is long-term recoverable.
• encryptProgress: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_Security_StartFoxitDRMEncryption	(	FSCRT_DOCUMENT	document,
		const FSCRT_BSTR *	subFilter,
		FS_BOOL	isOwner,
		FS_DWORD	userPermissions,
		FS_INT32	cipher,
		FS_INT32	keyLen,
		const FSCRT_BSTR *	fileID,
		const FSCRT_BSTR *	initialKey,
		FS_BOOL	encryptMetadata,
		FSCRT_FILE	encryptedFile,
		FS_INT32	flag,
		FSCRT_PROGRESS *	encryptProgress
	)

Start PDF document encryption by using Foxit DRM.

It will take a long time to encrypt a document with complex or large contents, so Foxit PDF SDK uses a progressive process to do this.
Caller should pass encryptProgress to function FSCRT_Progress_Continue to continue saving in steps, and should call function FSCRT_Progress_Release to destroy encryptProgress object if saving process is done. If caller wants to change the saved PDF file version, it can call function FSCRT_Progress_SetProperty to set "fileversion".

Parameters

[in]	document	Handle to a FSCRT_DOCUMENT object which is a PDF document object.
[in]	subFilter	Pointer to a FSCRT_BSTR structure to specify a subfilter.
[in]	isOwner	A boolean used to indicate to encrypt PDF file as owner or user: TRUE means owner, or FALSE means user.
[in]	userPermissions	User permission flags which is used to encrypt PDF document. Please refer to macro definitions FSPDF_PERMISSION_XXX and this can be one or a combination of these macros.
[in]	cipher	Encryption algorithm. It should be one of the following macro definitions: FSCRT_CIPHER_AES FSCRT_CIPHER_RC4
[in]	keyLen	Length of encryption algorithm, in bytes. For FSCRT_CIPHER_AES, this can be 16 or 32. For FSCRT_CIPHER_RC4, this should be in the range from 5 to 16, including 5 and 16.
[in]	fileID	Pointer to a FSCRT_BSTR structure that specifies file identity code. This can be empty but its usage is highly recommended.
[in]	initialKey	Pointer to a FSCRT_BSTR structure which is an initial key data. This can be empty but its usage is highly recommended.
[in]	encryptMetadata	Indicates whether encrypt metadata or not.
[in]	encryptedFile	Handle to a FSCRT_FILE object used to save encrypted PDF file.
[in]	flag	An integer value to specify saving mode. Please refer to macro definitions FSPDF_SAVEFLAG_XXX and this can be one or a combination of these macros except FSPDF_SAVEFLAG_REMOVESECURITY, FSPDF_SAVEFLAG_INCREMENTONLY and FSPDF_SAVEFLAG_LINEARIZED.
[out]	encryptProgress	Pointer to a FSCRT_PROGRESS handle that receives a handle of progressive process.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter document, subFilter, encryptedFile, or encryptProgress is NULL, or parameter cipher or flag is invalid.
FSCRT_ERRCODE_INVALIDLICENSE if the current license is not authorized or Foxit DRM security is not allowed.
FSCRT_ERRCODE_INVALIDMODULE if PDF module is not initialized.
FSCRT_ERRCODE_INVALIDTYPE if parameter document is not a type of PDF document.
FSCRT_ERRCODE_UNSUPPORTED if parameter cipher or keyBytes is not applicable.
FSCRT_ERRCODE_UNRECOVERABLE if function finds an unrecoverable error internally.
FSCRT_ERRCODE_OUTOFMEMORY if there is not enough memory or if the memory access is wrong.
FSCRT_ERRCODE_ERROR if document cannot be encrypted because of any other reason.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Note

Parameter encryptedFile should have WRITE callback functions implemented in structure FSCRT_FILEHANDLER.
If data cannot be written into parameter encryptedFile, FSCRT_ERRCODE_ERROR will return on calling function FSCRT_Progress_Continue during the next steps.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term unrecoverable.
• document: this handle is long-term partially recoverable.
• encryptedFile: this handle is long-term recoverable.
• encryptProgress: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_Security_StartPasswordEncryption	(	FSCRT_DOCUMENT	document,
		FS_DWORD	userPermissions,
		const FSCRT_BSTR *	userPassword,
		const FSCRT_BSTR *	ownerPassword,
		FS_INT32	cipher,
		FS_INT32	keyLen,
		FS_BOOL	encryptMetadata,
		FSCRT_FILE	encryptedFile,
		FS_INT32	flag,
		FSCRT_PROGRESS *	encryptProgress
	)

Start standard password encryption on a PDF document.

It will take a long time to encrypt a document with complex or large contents, so Foxit PDF SDK uses a progressive process to do this.
Caller should pass parameter encryptProgress to function FSCRT_Progress_Continue to continue encrypting in steps, and should call function FSCRT_Progress_Release to destroy encryptProgress object if encrypting process is done. If caller wants to change the saved PDF file version, call function FSCRT_Progress_SetProperty to set "fileversion".

Parameters

[in]	document	Handle to a FSCRT_DOCUMENT object which is a PDF document object.
[in]	userPermissions	Permission flags. Please refer to macro definitions FSPDF_PERMISSION_XXX and this can be one or a combination of these macros.
[in]	userPassword	Pointer to a FSCRT_BSTR structure that the user password, which could be set to NULL.
[in]	ownerPassword	Pointer to a FSCRT_BSTR structure that the owner password, which could be set to NULL.
[in]	cipher	The type of encryption algorithm. It should be one of the following macro definitions: FSCRT_CIPHER_AES FSCRT_CIPHER_RC4
[in]	keyLen	Key length of parameter cipher, in bytes. For FSCRT_CIPHER_AES, this can only be 16 or 32. For FSCRT_CIPHER_RC4, this should be between 5 and 16.
[in]	encryptMetadata	Whether to encrypt the metadata or not. This must be TRUE if cipher is FSCRT_CIPHER_RC4 and keyLen is 5.
[in]	encryptedFile	Handle to a FSCRT_FILE object used to save encrypted PDF file.
[in]	flag	An integer value to specify saving mode. Please refer to macro definitions FSPDF_SAVEFLAG_XXX and this can be one or a combination of these macros except FSPDF_SAVEFLAG_REMOVESECURITY, FSPDF_SAVEFLAG_INCREMENTONLY and FSPDF_SAVEFLAG_LINEARIZED.
[out]	encryptProgress	Pointer to a FSCRT_PROGRESS handle that receives a handle of progressive process.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter document, encryptedFile, or encryptProgress is NULL, or parameter flag is invalid, or any other parameter is unexpected.
FSCRT_ERRCODE_INVALIDLICENSE if the current license is not authorized or standard password security is not allowed.
FSCRT_ERRCODE_INVALIDTYPE if parameter document is not a type of PDF document.
FSCRT_ERRCODE_INVALIDMODULE if PDF module is not initialized.
FSCRT_ERRCODE_UNSUPPORTED if parameter cipher is not applicable.
FSCRT_ERRCODE_UNRECOVERABLE if function finds an unrecoverable error internally.
FSCRT_ERRCODE_OUTOFMEMORY if there is not enough memory or if the memory access is wrong.
FSCRT_ERRCODE_ERROR if document cannot be encrypted because of any other reason.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Note

Parameter encryptedFile should have WRITE callback functions implemented in structure FSCRT_FILEHANDLER.
If data cannot be written into parameter encryptedFile, FSCRT_ERRCODE_ERROR will return on calling function FSCRT_Progress_Continue during the next steps.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term recoverable.
• document: this handle is long-term partially recoverable.
• encryptedFile: this handle is long-term recoverable.
• encryptProgress: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_Security_StartRMSEncryption	(	FSCRT_DOCUMENT	document,
		const FSCRT_BSTR *	publishLicense,
		const FSCRT_BSTR *	serverEulList,
		FS_INT32	listCount,
		FS_INT32	irmVersion,
		FS_BOOL	encryptMetadata,
		FSCRT_FILE	encryptedFile,
		FS_INT32	flag,
		FSCRT_PROGRESS *	encryptProgress
	)

Start PDF document encryption by using Microsoft RMS.

In order to do Microsoft RMS encryption and decryption, applictaion should implement a FSPDF_SECURITYHANDLER structure first, and call function FSPDF_Security_RegisterHandler to register this handler with specific filter "MicrosoftIRMServices". Then application can call this function to do Microsoft RMS encryption to a PDF file, or call function FSPDF_Doc_StartLoad to load a PDF file encrypted by Microsoft RMS. Application should remember to call function FSPDF_Security_UnregisterHandler when no need to use Microsoft RMS encryption and decryption.

Parameters

[in]	document	Handle to a FSCRT_DOCUMENT object which is a PDF document object.
[in]	publishLicense	Pointer to a FSCRT_BSTR structure that specifies Encoded Publishing License issued from server to the Content publisher. This field contains the publishing license from Microsoft IRM services or a comparable IRM service. The original data of Publishing License should be compressed by Flate compression algorithm at first, and then encoded by Base-64 Encryption algorithm.
[in]	serverEulList	Pointer to a FSCRT_BSTR structure specifies a string array. NULL means no use. In this array, 2 strings are in a pair, and each pair represents content of a dictionary object which is encoded Server EUL. For each pair, the first string is ServerID, and the second one is ServerEUL. The original data of Server ID and Server EUL should be compressed by Flate compression algorithm at first, and then encoded by Base-64 Encryption algorithm.
[in]	listCount	Count of elements in array serverEulList. This should be multiply of 2. This is useful only when if parameter serverEulList is valid.
[in]	irmVersion	Microsoft IRM version. Default: 1.
[in]	encryptMetadata	A boolean used to indicate whether to encrypt the meta data or not.
[in]	encryptedFile	Handle to a FSCRT_FILE object used to save encrypted PDF file.
[in]	flag	An integer value to specify saving mode. Please refer to macro definitions FSPDF_SAVEFLAG_XXX and this should be one of these macros except FSPDF_SAVEFLAG_REMOVESECURITY, FSPDF_SAVEFLAG_INCREMENTONLY and FSPDF_SAVEFLAG_LINEARIZED.
[out]	encryptProgress	Handle to a FSCRT_PROGRESS object used to continue the encryption progress.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter document, encryptedFile, or encryptProgress is NULL, or parameter publishLicense is NULL or empty, or parameter listCount is below 2 or not a multiply of 2 when parameter serverEulList is valid, or parameter flag is invalid.
FSCRT_ERRCODE_INVALIDLICENSE if the current license is not authorized or Microsoft RMS security is not allowed.
FSCRT_ERRCODE_INVALIDMODULE if PDF module is not initialized.
FSCRT_ERRCODE_INVALIDTYPE if parameter document is not a type of PDF document.
FSCRT_ERRCODE_UNKNOWNSECURITYHANDLER if valid security handler used for Microsoft RMS cannot be found.
FSCRT_ERRCODE_UNRECOVERABLE if function finds an unrecoverable error internally.
FSCRT_ERRCODE_OUTOFMEMORY if there is not enough memory or if the memory access is wrong.
FSCRT_ERRCODE_ERROR if document cannot be encrypted because of any other reason.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term recoverable.
• document: this handle is long-term partially recoverable.
• encryptedFile: this handle is long-term recoverable.
• encryptProgress: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_Security_UnregisterHandler

(

const FSCRT_BSTR *

filter

)

Unregister a customer security handler to Foxit PDF SDK.

This function is only used for custom encryption and decryption.

Parameters

[in]

filter

Pointer to FSCRT_BSTR structure that specifies a security filter. It should be registered by previous call to the function FSPDF_Security_RegisterHandler.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter filter is NULL.
FSCRT_ERRCODE_INVALIDMANAGER if Foxit PDF SDK manager is not initialized.
FSCRT_ERRCODE_INVALIDMODULE if PDF module is not initialized.
FSCRT_ERRCODE_NOTFOUND if no parameter filter is found.
FSCRT_ERRCODE_ERROR if the handler cannot be unregistered because of any other reason.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_Security_VerifyFoxitDRMEncryptionParams	(	FSCRT_DOCUMENT	document,
		FS_BOOL *	verified
	)

Verify encryption parameters in a PDF document.

Foxit DRM maintains a set of encryption parameters for application purpose. Encryption parameters are stored in PDF file and protected by verification algorithm. So application should call this function to verify the current PDF document. If verification is failed, the document might be distorted.

Parameters

[in]	document	Handle to a FSCRT_DOCUMENT object which is a PDF document object.
[out]	verified	Pointer to a FS_BOOL object that receives verification result: TRUE for success, or FALSE for failure.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter document or verified is NULL.
FSCRT_ERRCODE_INVALIDLICENSE if the current license is not authorized or Foxit DRM security is not allowed.
FSCRT_ERRCODE_INVALIDTYPE if parameter document is not a type of PDF document, or document is not a Foxit DRM encrypted one.
FSCRT_ERRCODE_UNRECOVERABLE if function finds an unrecoverable error internally.
FSCRT_ERRCODE_OUTOFMEMORY if there is not enough memory or if the memory access is wrong.
FSCRT_ERRCODE_ERROR if cannot verify document because of any other reason.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Note

Do not use this function for a non-Foxit DRM encrypted file.
Call function FSPDF_Doc_GetEncryptionType to determine if a PDF document is encrypted by Foxit DRM.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term unrecoverable.
• document: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.