Interface SecurityHandler
-
public interface SecurityHandler
SecurityHandler
performs the main actions required to decrypt or encrypt a PDF document. In the case of decryption, theSecurityHandler
authenticates the right to decrypt the document. For example, password-basedSecurityHandler
validitates the password in the process of authentication.SecurityHandler
also delivers (on decryption) or determines (on encryption) encryption permissions. For the password-based security handlers, this is the content of the /P entry in the Encrypt dictionary; the public-key-based security handlers get the encryption permissions from the proper PKCS#7 object in the Recipients array in the Encrypt dictionary. Other security handlers implementations may get/set encryption permissions as they deem appropriate. Therefore theSecurityHandler
interface contains the method that returnsPermissionsProvider
that handles encryption permissions.SecurityHandler
declares the interfaces for a specific security handler in aPDFDocument
.The security handler provides the following functionality:
- Authenticates the access rights to an encrypted PDF document.
- Computes the base encryption key.
- Computes the object-specific encryption key for each PDF object (String or Stream).
- Uses the object-specific encryption key to encrypt or decrypt (String or Stream) content.
- All Security Handler implementations must support Crypt filters listed in the Encrypt dictionary. Specifically, they must support Identity Crypt filter.
The PDF Java ToolKit provides the following password-based security handler.
- Standard This security handler provides support for RC4 and AES encryption technologies.
The names for other security handlers can be registered by using the procedure described in the PDF Reference, Appendix E.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description boolean
authenticate(Map params, byte[] docID)
Authenticates the right to decrypt and access the document.boolean
authenticate(Map params, byte[] docID, DecryptedState decryptedState)
Authenticates the right to decrypt and access the document by plugging in the decrypted state of the document.DecryptedState
getDecryptedState()
Returns decrypted state of the document.EncryptionHandler
getEncryptionHandler(String cryptName, Map encryptParams, byte[] docId)
Instantiates an encryption handler that performs the actual encryption/decryption operations with the base encryption key calculated by this security handler.Map
getEncryptParameters()
Get the encryption parameters specified by this Security Handler This can be either the original Encryption Parameters Map that were passed in thegetEncryptionHandler(String, Map, byte[])
call with some entries possibly changed.PermissionProvider
getPermissionProvider()
Fetch the permission provider that specifies encryption permissions associated with this security handler.
-
-
-
Method Detail
-
getEncryptionHandler
EncryptionHandler getEncryptionHandler(String cryptName, Map encryptParams, byte[] docId) throws PDFSecurityAuthorizationException, PDFSecurityConfigurationException
Instantiates an encryption handler that performs the actual encryption/decryption operations with the base encryption key calculated by this security handler. To implement this, Security Handler should authenticate the access rights to the encrypted document before it instantiates the encryption handler.- Parameters:
cryptName
- the name of the Crypt FilterencryptParams
- the Encryption Parameters Map containing encryption parameters for encryption. Depending on the implementation it may or may not be the same Encryption Parameters Map used in decryption.SecurityHandler
may cache or discard it.docId
- the first Document ID string in the PDF documents trailer.- Returns:
EncryptionHandler
encryption handler that performs encryption/decryption for this security handler. This handler may be cached by the Security Handler for reuse as required.- Throws:
PDFSecurityAuthorizationException
PDFSecurityConfigurationException
- See Also:
authenticate(Map, byte[])
-
getEncryptParameters
Map getEncryptParameters()
Get the encryption parameters specified by this Security Handler This can be either the original Encryption Parameters Map that were passed in thegetEncryptionHandler(String, Map, byte[])
call with some entries possibly changed. It could also be a completely new Map created in the SecurityHandler and used to encrypt content. Security Handler should not change Encryption Parameters Map used to decrypt the contentIn instances of the Security Handler for decryption this method may return
null
because no encryption parameters were saved.- Returns:
- Map that contains encryption parameters.
-
authenticate
boolean authenticate(Map params, byte[] docID) throws PDFSecurityAuthorizationException, PDFSecurityConfigurationException
Authenticates the right to decrypt and access the document.This method is usually called for the default Security Handler by the Security Support implementation to ensure the ability to process PDF document. Because particular streams may use different Security Handlers for encryption (or decryption), the authentication of these Security Handlers may happen, depending on the implementation, in the
getEncryptionHandler(String, Map, byte[])
call.- Parameters:
params
- the Encryption Parameters Map containing encryption parameters for encryption. Depending on the implementation it may or may not be the same Encryption Parameters Map used in decryption.SecurityHandler may cache or discard the parameters map.
docID
- the first Document ID string in the PDF documents trailer.- Throws:
PDFSecurityAuthorizationException
PDFSecurityConfigurationException
-
getPermissionProvider
PermissionProvider getPermissionProvider()
Fetch the permission provider that specifies encryption permissions associated with this security handler.
-
authenticate
boolean authenticate(Map params, byte[] docID, DecryptedState decryptedState) throws PDFSecurityConfigurationException, PDFSecurityAuthorizationException
Authenticates the right to decrypt and access the document by plugging in the decrypted state of the document.- Parameters:
params
- the Encryption Parameters Map containing encryption parameters for encryption. Depending on the implementation it may or may not be the same Encryption Parameters Map used in decryption.SecurityHandler may cache or discard the parameters map.
docID
- the first Document ID string in the PDF documents trailer.decryptedState
- Decrypted state of the document- Throws:
PDFSecurityAuthorizationException
PDFSecurityConfigurationException
-
getDecryptedState
DecryptedState getDecryptedState()
Returns decrypted state of the document. If authenticate method has not been called, then this method returns null.- Returns:
- DecryptedState
-
-