org.apache.pdfbox.pdmodel.encryption

## Class SecurityHandler<TPOLICY extends ProtectionPolicy>

- java.lang.Object
- - org.apache.pdfbox.pdmodel.encryption.SecurityHandler<TPOLICY>

Type Parameters:
  `TPOLICY` - the protection policy.

Direct Known Subclasses:
  PublicKeySecurityHandler, StandardSecurityHandler

    public abstract class SecurityHandler<TPOLICY extends ProtectionPolicy>
    extends Object

A security handler as described in the PDF specifications. A security handler is responsible of documents protection.

Author:
  Ben Litchfield, Benoit Guillon, Manuel Kasper

### Constructor Summary

Constructors
`protected` `SecurityHandler()` Constructor.
`protected` `SecurityHandler(TPOLICY protectionPolicy)` Constructor used for encryption.

### Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
`protected int` `computeVersionNumber()` Computes the version number of the `SecurityHandler` based on the encryption key length.
`COSBase` `decrypt(COSBase obj, long objNum, long genNum)` This will dispatch to the correct method.
`void` `decryptStream(COSStream stream, long objNum, long genNum)` This will decrypt a stream.
`protected void` `encryptDataRC4(byte[] finalKey, byte[] input, OutputStream output)` Encrypt or decrypt data with RC4.
`protected void` `encryptDataRC4(byte[] finalKey, InputStream input, OutputStream output)` Encrypt or decrypt data with RC4.
`void` `encryptStream(COSStream stream, long objNum, int genNum)` This will encrypt a stream, but not the dictionary as the dictionary is encrypted by visitFromString() in COSWriter and we don't want to encrypt it twice.
`void` `encryptString(COSString string, long objNum, int genNum)` This will encrypt a string.
`AccessPermission` `getCurrentAccessPermission()` Returns the access permissions that were computed during document decryption.
`byte[]` `getEncryptionKey()` Returns the current encryption key data.
`int` `getKeyLength()` Getter of the property keyLength.
`protected TPOLICY` `getProtectionPolicy()` Returns the set `ProtectionPolicy` or null.
`boolean` `hasProtectionPolicy()` Returns whether a protection policy has been set.
`boolean` `isAES()` True if AES is used for encryption and decryption.
`boolean` `isDecryptMetadata()` Returns true if meta data is to be decrypted.
`abstract void` `prepareDocumentForEncryption(PDDocument doc)` Prepare the document for encryption.
`abstract void` `prepareForDecryption(PDEncryption encryption, COSArray documentIDArray, DecryptionMaterial decryptionMaterial)` Prepares everything to decrypt the document.
`void` `setAES(boolean aesValue)` Set to true if AES for encryption and decryption should be used.
`void` `setCurrentAccessPermission(AccessPermission currentAccessPermission)` Sets the access permissions.
`void` `setCustomSecureRandom(SecureRandom customSecureRandom)` Set the custom SecureRandom.
`protected void` `setDecryptMetadata(boolean decryptMetadata)` Set whether to decrypt meta data.
`void` `setEncryptionKey(byte[] encryptionKey)` Sets the current encryption key data.
`void` `setKeyLength(int keyLen)` Setter of the property keyLength.
`protected void` `setProtectionPolicy(TPOLICY protectionPolicy)` Sets the `ProtectionPolicy` to the given value.
`protected void` `setStreamFilterName(COSName streamFilterName)` Set the stream filter name.
`protected void` `setStringFilterName(COSName stringFilterName)` Set the string filter name.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### SecurityHandler

    protected SecurityHandler()

Constructor.

#### SecurityHandler

    protected SecurityHandler(TPOLICY protectionPolicy)

Constructor used for encryption.

Parameters:
  `protectionPolicy` - The protection policy.

### Method Detail

#### setDecryptMetadata

    protected void setDecryptMetadata(boolean decryptMetadata)

Set whether to decrypt meta data.

Parameters:
  `decryptMetadata` - true if meta data has to be decrypted.

#### isDecryptMetadata

    public boolean isDecryptMetadata()

Returns true if meta data is to be decrypted.

Returns:
  True if meta data has to be decrypted.

#### setStringFilterName

    protected void setStringFilterName(COSName stringFilterName)

Set the string filter name.

Parameters:
  `stringFilterName` - the string filter name.

#### setStreamFilterName

    protected void setStreamFilterName(COSName streamFilterName)

Set the stream filter name.

Parameters:
  `streamFilterName` - the stream filter name.

#### setCustomSecureRandom

    public void setCustomSecureRandom(SecureRandom customSecureRandom)

Set the custom SecureRandom.

Parameters:
  `customSecureRandom` - the custom SecureRandom for AES encryption

#### prepareDocumentForEncryption

    public abstract void prepareDocumentForEncryption(PDDocument doc)
                                               throws IOException

Prepare the document for encryption.

Parameters:
  `doc` - The document that will be encrypted.
Throws:
  `IOException` - If there is an error with the document.

#### prepareForDecryption

    public abstract void prepareForDecryption(PDEncryption encryption,
                                              COSArray documentIDArray,
                                              DecryptionMaterial decryptionMaterial)
                                       throws IOException

Prepares everything to decrypt the document.

Parameters:
  `encryption` - encryption dictionary, can be retrieved via `PDDocument.getEncryption()`
  `documentIDArray` - document id which is returned via `COSDocument.getDocumentID()`
  `decryptionMaterial` - Information used to decrypt the document.
Throws:
  `InvalidPasswordException` - If the password is incorrect.
  `IOException` - If there is an error accessing data.

#### encryptDataRC4

    protected void encryptDataRC4(byte[] finalKey,
                                  InputStream input,
                                  OutputStream output)
                           throws IOException

Encrypt or decrypt data with RC4.

Parameters:
  `finalKey` - The final key obtained with via `calcFinalKey(long, long)`.
  `input` - The data to encrypt.
  `output` - The output to write the encrypted data to.
Throws:
  `IOException` - If there is an error reading the data.

#### encryptDataRC4

    protected void encryptDataRC4(byte[] finalKey,
                                  byte[] input,
                                  OutputStream output)
                           throws IOException

Encrypt or decrypt data with RC4.

Parameters:
  `finalKey` - The final key obtained with via `calcFinalKey(long, long)`.
  `input` - The data to encrypt.
  `output` - The output to write the encrypted data to.
Throws:
  `IOException` - If there is an error reading the data.

#### decrypt

    public COSBase decrypt(COSBase obj,
                           long objNum,
                           long genNum)
                    throws IOException

This will dispatch to the correct method.

Parameters:
  `obj` - The object to decrypt.
  `objNum` - The object number.
  `genNum` - The object generation Number.
Throws:
  `IOException` - If there is an error getting the stream data.

#### decryptStream

    public void decryptStream(COSStream stream,
                              long objNum,
                              long genNum)
                       throws IOException

This will decrypt a stream.

Parameters:
  `stream` - The stream to decrypt.
  `objNum` - The object number.
  `genNum` - The object generation number.
Throws:
  `IOException` - If there is an error getting the stream data.

#### encryptStream

    public void encryptStream(COSStream stream,
                              long objNum,
                              int genNum)
                       throws IOException

This will encrypt a stream, but not the dictionary as the dictionary is encrypted by visitFromString() in COSWriter and we don't want to encrypt it twice.

Parameters:
  `stream` - The stream to decrypt.
  `objNum` - The object number.
  `genNum` - The object generation number.
Throws:
  `IOException` - If there is an error getting the stream data.

#### encryptString

    public void encryptString(COSString string,
                              long objNum,
                              int genNum)
                       throws IOException

This will encrypt a string.

Parameters:
  `string` - the string to encrypt.
  `objNum` - The object number.
  `genNum` - The object generation number.
Throws:
  `IOException` - If an error occurs writing the new string.

#### getKeyLength

    public int getKeyLength()

Getter of the property keyLength.

Returns:
  Returns the keyLength in bits.

#### setKeyLength

    public void setKeyLength(int keyLen)

Setter of the property keyLength.

Parameters:
  `keyLen` - The keyLength to set in bits.

#### setCurrentAccessPermission

    public void setCurrentAccessPermission(AccessPermission currentAccessPermission)

Sets the access permissions.

Parameters:
  `currentAccessPermission` - The access permissions to be set.

#### getCurrentAccessPermission

    public AccessPermission getCurrentAccessPermission()

Returns the access permissions that were computed during document decryption. The returned object is in read only mode.

Returns:
  the access permissions or null if the document was not decrypted.

#### isAES

    public boolean isAES()

True if AES is used for encryption and decryption.

Returns:
  true if AEs is used

#### setAES

    public void setAES(boolean aesValue)

Set to true if AES for encryption and decryption should be used.

Parameters:
  `aesValue` - if true AES will be used

#### hasProtectionPolicy

    public boolean hasProtectionPolicy()

Returns whether a protection policy has been set.

Returns:
  true if a protection policy has been set.

#### getProtectionPolicy

    protected TPOLICY getProtectionPolicy()

Returns the set `ProtectionPolicy` or null.

Returns:
  The set `ProtectionPolicy`.

#### setProtectionPolicy

    protected void setProtectionPolicy(TPOLICY protectionPolicy)

Sets the `ProtectionPolicy` to the given value.

Parameters:
  `protectionPolicy` - The `ProtectionPolicy`, that shall be set.

#### getEncryptionKey

    public byte[] getEncryptionKey()

Returns the current encryption key data.

Returns:
  The current encryption key data.

#### setEncryptionKey

    public void setEncryptionKey(byte[] encryptionKey)

Sets the current encryption key data.

Parameters:
  `encryptionKey` - The encryption key data to set.

#### computeVersionNumber

    protected int computeVersionNumber()

Computes the version number of the `SecurityHandler` based on the encryption key length. See PDF Spec 1.6 p 93 and PDF 1.7 Supplement ExtensionLevel: 3 and PDF Spec 2.0.

Returns:
  The computed version number.