Package com.adobe.internal.pdftoolkit.core.securityframework

Interface SecurityHandler

  • public interface SecurityHandler
    SecurityHandler performs the main actions required to decrypt or encrypt a PDF document. In the case of decryption, the SecurityHandler authenticates the right to decrypt the document. For example, password-based SecurityHandler 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 the SecurityHandler interface contains the method that returns PermissionsProvider that handles encryption permissions.

    SecurityHandler declares the interfaces for a specific security handler in a PDFDocument.

    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​(java.util.Map params, byte[] docID)
      Authenticates the right to decrypt and access the document.
      boolean authenticate​(java.util.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​(java.lang.String cryptName, java.util.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.
      java.util.Map getEncryptParameters()
      Get the encryption parameters specified by this Security Handler This can be either the original Encryption Parameters Map that were passed in the getEncryptionHandler(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​(java.lang.String cryptName,
                                       java.util.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 Filter
        encryptParams - 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 document’s 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

        java.util.Map getEncryptParameters()
        Get the encryption parameters specified by this Security Handler This can be either the original Encryption Parameters Map that were passed in the getEncryptionHandler(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 content

        In 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​(java.util.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 document’s trailer.
        Throws:
        PDFSecurityAuthorizationException
        PDFSecurityConfigurationException

      • getPermissionProvider

        PermissionProvider getPermissionProvider()
        Fetch the permission provider that specifies encryption permissions associated with this security handler.

      • authenticate

        boolean authenticate​(java.util.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 document’s 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