EncryptionDictionary (ICEpdf API)

java.lang.Object
- org.icepdf.core.pobjects.Dictionary
- - org.icepdf.core.pobjects.security.EncryptionDictionary

public class EncryptionDictionary
extends Dictionary

The EncryptionDictionary class is used to hold values needed by the Standard Security Handler, Public Key Handlers and Crypt filters. This PDF object is found via a document's Trailer object, but only when the Trailer has an encrypted named reference.

The dictionary is composed of combinations of the following entries defined by the different encryption types. ICEpdf currently only supports the Standard Security Handler.

Common to all Encryption Dictionaries
Key	Type	Value
Filter	name	(Required) The name of the preferred security handler for this document; typically it is the name of the security handler that was used to encrypt the document. If SubFilter is not present, only this security handler should be used when opening the document. If it is present, viewer applications are free to use any security handler that implements the format specified by SubFilter.
SubFilter	name	(Optional; PDF 1.3) A name that completely specifies the format and interpretation of the contents of the encryption dictionary. It is needed in order to allow security handlers other than the one specified by Filter to decrypt the document. If it is absent, other security handlers will not be able to decrypt the document.
V	number	(Optional but strongly recommended) A code specifying the algorithm to be used in encrypting and decrypting the document: 0 - An algorithm that is undocumented and no longer supported, and whose use is strongly discouraged. 1 - Algorithm 3.1, with an encryption key length of 40 bits; see below. 2 - (PDF 1.4) Algorithm 3.1, but allowing encryption key lengths greater than 40 bits. 3 - (PDF 1.4) An unpublished algorithm allowing encryption key lengths ranging from 40 to 128 bits. (This algorithm is unpublished as an export requirement of the U.S. Department of Commerce.) (PDF 1.5) The security handler defines the use of encryption and decryption in the document, using the rules specified by the CF, StmF, and StrF entries.
Length	integer	(Optional; PDF 1.4; only if V is 2 or 3) The length of the encryption key, in bits. The value must be a multiple of 8, in the range 40 to 128. Default value: 40.
CF	dictionary	(Optional; meaningful only when the value of V is 4; PDF 1.5) A dictionary whose keys are crypt filter names and whose values are the corresponding crypt filter dictionaries.
StmF	name	(Optional; meaningful only when the value of V is 4; PDF 1.5) The name of the crypt filter that is used by default when encrypting streams; it must correspond to a key in the CF dictionary or a standard crypt filter name. All streams in the document, except for cross-reference streams or those that have a crypt entry in their Filter array are decrypted by the security handler, using this crypt filter.
StrF	name	(Optional; meaningful only when the value of V is 4; PDF 1.5) The name of the crypt filter that is used when decrypting all strings in the document; it must correspond to a key in the CF dictionary or a standard crypt filter name.

The dictionary composes of the following values that can be returned via their named mehtod or by a generic getValue method if the key's name is known. The values of the O and U entries in this dictionary are used to determine whether a password entered when the document is opened is the correct owner password, user password, or neither.

Standard Encryption Dictionary Entries
Key	Type	Value
R	number	(Required) A number specifying which revision of the standard security handler should be used to interpret this dictionary. The revision number should be: 2 if the document is encrypted with a V value less than 2 and does not have any of the access permissions set (via the P entry, below) that are designated "Revision3" 3 if the document is encrypted with a V value of 2 or 3, or has any "Revision 3" access permissions set. 4 if the document is encrypted with a V value of 4.
O	String	(Required) A 32-byte string, based on both the owner and user passwords, that is used in computing the encryption key and in determining whether a valid owner password was entered.
U	String	U string (Required) A 32-byte string, based on the user password, that is used in determining whether to prompt the user for a password and, if so, whether a valid user or owner password was entered.
P	Integer	(Required) A set of flags specifying which operations are permitted when the document is opened with user access.

Encryption dictionaries for public-key security handlers contain the common entries shown above. In addition, they may contain the entries shown below.

Additional public-key Dictionary Entries
Key	Type	Value
Recipients	array	(Required when SubFilter is adbe.pkcs7.s3 or adbe.pkcs7.s4; PDF 1.3) An array of strings, where each string is a PKCS#7 object listing recipients that have been granted equal access rights to the document. The data contained in the PKCS#7 object includes both a cryptographic key that is used to decrypt the encrypted data and the access permissions that apply to the recipient list. There should be only one object per unique set of access permissions; if a recipient appears in more than one list, the permissions used will be those found in the first matching list. Note: When SubFilter is adbe.pkcs7.s5, recipient lists are specified in the crypt filter dictionary.

Encryption dictionaries for crypt filter security handlers contain the common entries shown above. In addition, they may contain the entries shown below

Standard Encryption Dictionary Entries
Key	Type	Value
Type	name	(Optional) If present, must be CryptFilter for a crypt filter dictionary.
CFM	name	(Optional) The method used, if any, by the viewer application to decrypt data. In PDF 1.5, the following values are supported: None: (default)the viewer application does not decrypt data, but directs the input stream to the security handler for decryption. V2: the viewer application asks the security handler for the decryption key and implicitly decrypts data using Algorithm 3.1. A viewer application may ask once for this decryption key, then cache the key for subsequent use for streams that use the same crypt filter; therefore, there must be a one-to-one relationship between a crypt filter name and the corresponding decryption key.
Length	integer	(Optional) When the value of CFM is V2, this entry is used to indicate the bit length of the decryption key. It must be a multiple of 8 in the range of 40 to 128. Default value: 128. When the value of CFM is None, security handlers can define their own use of this entry, but are encouraged to follow the usage conventions defined for V2.
AuthEvent	name	(Optional) The event to be used to trigger the authorization that is required to access decryption keys used by this filter. If authorization fails, the event should fail. Acceptable values are: DocOpen: (default) authorization is required when a document is opened. EFOpen: authorization is required when about to access embedded files. If this filter is used as the value of StrF or StmF in the encryption dictionary, the viewer application should ignore this key and behave as if the value is DocOpen.

Since:: 1.1

Field Summary

Fields
Modifier and Type	Field and Description
`static Name`	`CF_KEY`
`static Name`	`EEF_KEY`
`static Name`	`ENCRYPT_METADATA_KEY`
`static Name`	`FILTER_KEY`
`static Name`	`LENGTH_KEY`
`static Name`	`O_KEY`
`static Name`	`OE_KEY`
`static Name`	`P_KEY`
`static Name`	`PERMS_KEY`
`static Name`	`R_KEY`
`static Name`	`STMF_KEY`
`static Name`	`STRF_KEY`
`static Name`	`SUB_FILTER_KEY`
`static Name`	`U_KEY`
`static Name`	`UE_KEY`
`static Name`	`V_KEY`

Fields inherited from class org.icepdf.core.pobjects.Dictionary
entries, FORM_TYPE_KEY, inited, isDeleted, isNew, library, SUBTYPE_KEY, TYPE_KEY

Constructor Summary

Constructors
Constructor and Description
`EncryptionDictionary(Library lib, java.util.HashMap<java.lang.Object,java.lang.Object> encryptionDictionary, java.util.List fileID)` Creates a new Encryption Dictionary object.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`java.lang.String`	`getBigO()` Gets the 32-byte string used for verifying the owner password.
`java.lang.String`	`getBigOE()` Gets the 32-byte string, based on the owner and user passwords, that is used in the computing the encryption key.
`java.lang.String`	`getBigU()` Gets the 32-byte string used for verifying the user password.
`java.lang.String`	`getBigUE()` Gets the 32-byte string, based on the user password, that is used in the computing the encryption key.
`CryptFilter`	`getCryptFilter()` (Optional; meaningful only when the value of V is 4; PDF 1.5) A dictionary whose keys shall be crypt filter names and whose values shall be the corresponding crypt filter dictionaries (see Table 25).
`Name`	`getEEF()` (Optional; meaningful only when the value of V is 4; PDF 1.6) The name of the crypt filter that shall be used when encrypting embedded file streams that do not have their own crypt filter specifier; it shall correspond to a key in the CFdictionary or a standard crypt filter name specified in Table 26.
`java.util.List`	`getFileID()` Gets the document's File ID.
`int`	`getKeyLength()` Gets the length of the encryption key, in bits.
`int`	`getPermissions()` Gets the integer flag which specifies the operation permitted when the document is opened with user access.
`java.lang.String`	`getPerms()` A16-byte string, encrypted with the file encryption key, that contains an encrypted copy of the permission flags.
`Name`	`getPreferredSecurityHandlerName()` Gets the preferred security handler name.
`Name`	`getPreferredSecurityHandlerSubName()` Gets the preferred security handler sub-name.
`int`	`getRevisionNumber()` Gets the revision number of the standard security handler.
`Name`	`getStmF()` (Optional; meaningful only when the value of V is 4; PDF 1.5) The name of the crypt filter that shall be used by default when decrypting streams.
`Name`	`getStrF()` (Optional; meaningful only when the value of V is 4; PDF 1.5) The name of the crypt filter that shall be used when decrypting all strings in the document.
`java.lang.Object`	`getValue(java.lang.Object key)` Gets any dictionary key specified by the key parameter.
`int`	`getVersion()` Gets a code specifying the algorithm to be used in encrypting and decrypting the document: 0 An algorithm that is undocumented.
`protected boolean`	`isAuthenticatedOwnerPassword()`
`protected boolean`	`isAuthenticatedUserPassword()`
`boolean`	`isEncryptMetaData()` Indicates whether the document-level metadata stream (see Section 10.2.2, "Metadata Streams") is to be encrypted.
`protected void`	`setAuthenticatedOwnerPassword(boolean authenticatedOwnerPassword)`
`protected void`	`setAuthenticatedUserPassword(boolean authenticatedUserPassword)`
`java.lang.String`	`toString()` Returns a summary of the dictionary entries.

Methods inherited from class org.icepdf.core.pobjects.Dictionary
getEntries, getFloat, getInt, getLibrary, getNumber, getObject, getPObjectReference, init, isDeleted, isNew, setDeleted, setNew, setPObjectReference

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - FILTER_KEY
```
public static final Name FILTER_KEY
```
  - SUB_FILTER_KEY
```
public static final Name SUB_FILTER_KEY
```
  - V_KEY
```
public static final Name V_KEY
```
  - LENGTH_KEY
```
public static final Name LENGTH_KEY
```
  - R_KEY
```
public static final Name R_KEY
```
  - O_KEY
```
public static final Name O_KEY
```
  - U_KEY
```
public static final Name U_KEY
```
  - P_KEY
```
public static final Name P_KEY
```
  - CF_KEY
```
public static final Name CF_KEY
```
  - STMF_KEY
```
public static final Name STMF_KEY
```
  - STRF_KEY
```
public static final Name STRF_KEY
```
  - EEF_KEY
```
public static final Name EEF_KEY
```
  - OE_KEY
```
public static final Name OE_KEY
```
  - UE_KEY
```
public static final Name UE_KEY
```
  - PERMS_KEY
```
public static final Name PERMS_KEY
```
  - ENCRYPT_METADATA_KEY
```
public static final Name ENCRYPT_METADATA_KEY
```
- Constructor Detail
  - EncryptionDictionary
```
public EncryptionDictionary(Library lib,
                            java.util.HashMap<java.lang.Object,java.lang.Object> encryptionDictionary,
                            java.util.List fileID)
```
    Creates a new Encryption Dictionary object.
    
    Parameters:
    
    lib - library dictionary of all objects in document.
    
    encryptionDictionary - dictionary of all values taken from encrypt key in the documents Trailer reference.
    
    fileID - Vector containing the two file ID values originally parsed from the Trailer reference.
- Method Detail
  - getFileID
```
public java.util.List getFileID()
```
    Gets the document's File ID.
    
    Returns:
    
    vector containing two values that represent the file ID
  - getPreferredSecurityHandlerName
```
public Name getPreferredSecurityHandlerName()
```
    Gets the preferred security handler name.
    
    Returns:
    
    handler name.
  - getPreferredSecurityHandlerSubName
```
public Name getPreferredSecurityHandlerSubName()
```
    Gets the preferred security handler sub-name.
    
    Returns:
    
    handler sub-name.
  - getVersion
```
public int getVersion()
```
    Gets a code specifying the algorithm to be used in encrypting and decrypting the document:
    - 0 An algorithm that is undocumented. This value shall not be used.
    - 1 "Algorithm 1: Encryption of data using the RC4 or AES algorithms" in 7.6.2, "General Encryption Algorithm," with an encryption key length of 40 bits; see below.
    - 2 (PDF 1.4) "Algorithm 1: Encryption of data using the RC4 or AES algorithms"in 7.6.2, "General Encryption Algorithm," but permitting encryption key lengths greater than 40 bits.
    - 3(PDF 1.4) An unpublished algorithm that permits encryption key lengths ranging from 40 to 128 bits. This value shall not appear in a conforming PDF file.
    - 4(PDF 1.5) The security handler defines the use of encryption and decryption in the document, using the rules specified by the CF, StmF, and StrF entries. The default value if this entry is omitted shall be 0, but when present should be a value of 1 or greater.
    Returns:
    
    encryption version.
  - getKeyLength
```
public int getKeyLength()
```
    Gets the length of the encryption key, in bits.
    
    Returns:
    
    length of encryption key.
  - getRevisionNumber
```
public int getRevisionNumber()
```
    Gets the revision number of the standard security handler.
    
    Returns:
    
    revision number.
  - getBigO
```
public java.lang.String getBigO()
```
    Gets the 32-byte string used for verifying the owner password.
    
    Returns:
    
    32-byte string representing the key O.
  - getBigU
```
public java.lang.String getBigU()
```
    Gets the 32-byte string used for verifying the user password.
    
    Returns:
    
    32-byte string representing the key U.
  - getPermissions
```
public int getPermissions()
```
    Gets the integer flag which specifies the operation permitted when the document is opened with user access.
    
    Returns:
    
    return flag specifying user access.
  - getCryptFilter
```
public CryptFilter getCryptFilter()
```
    (Optional; meaningful only when the value of V is 4; PDF 1.5) A dictionary whose keys shall be crypt filter names and whose values shall be the corresponding crypt filter dictionaries (see Table 25). Every crypt filter used in the document shall have an entry in this dictionary, except for the standard crypt filter names (see Table 26).
    The conforming reader shall ignore entries in CF dictionary with the keys equal to those listed in Table 26 and use properties of the respective standard crypt filters.
    
    Returns:
    
    crypt filter object if found, null otherwise.
  - getStmF
```
public Name getStmF()
```
    (Optional; meaningful only when the value of V is 4; PDF 1.5) The name of the crypt filter that shall be used by default when decrypting streams. The name shall be a key in the CF dictionary or a standard crypt filter name specified in Table 26. All streams in the document, except for cross-reference streams (see 7.5.8, "Cross-Reference Streams") or streams that have a Crypt entry in their Filterarray (see Table 6), shall be decrypted by the security handler, using this crypt filter.
    Default value: Identity.
    
    Returns:
    
    name of the default stream filter name.
  - getStrF
```
public Name getStrF()
```
    (Optional; meaningful only when the value of V is 4; PDF 1.5) The name of the crypt filter that shall be used when decrypting all strings in the document. The name shall be a key in the CF dictionary or a standard crypt filter name specified in Table 26.
    Default value: Identity.
    
    Returns:
    
    name of the default string filter name.
  - getEEF
```
public Name getEEF()
```
    (Optional; meaningful only when the value of V is 4; PDF 1.6) The name of the crypt filter that shall be used when encrypting embedded file streams that do not have their own crypt filter specifier; it shall correspond to a key in the CFdictionary or a standard crypt filter name specified in Table 26.
    This entry shall be provided by the security handler. Conforming writers shall respect this value when encrypting embedded files, except for embedded file streams that have their own crypt filter specifier. If this entry is not present, and the embedded file stream does not contain a crypt filter specifier, the stream shall be encrypted using the default stream crypt filter specified by StmF.
    EFF:name
  - getBigOE
```
public java.lang.String getBigOE()
```
    Gets the 32-byte string, based on the owner and user passwords, that is used in the computing the encryption key.
    
    Returns:
    
    32-byte string representing the key OE.
  - getBigUE
```
public java.lang.String getBigUE()
```
    Gets the 32-byte string, based on the user password, that is used in the computing the encryption key.
    
    Returns:
    
    32-byte string representing the key UE.
  - getPerms
```
public java.lang.String getPerms()
```
    A16-byte string, encrypted with the file encryption key, that contains an encrypted copy of the permission flags.
    
    Returns:
    
    16-byte string representing the key Perms.
  - isEncryptMetaData
```
public boolean isEncryptMetaData()
```
    Indicates whether the document-level metadata stream (see Section 10.2.2, "Metadata Streams") is to be encrypted. Applications should respect this value.
    
    Returns:
    
    true if document-level metadata is encrypted
  - isAuthenticatedUserPassword
```
protected boolean isAuthenticatedUserPassword()
```
  - setAuthenticatedUserPassword
```
protected void setAuthenticatedUserPassword(boolean authenticatedUserPassword)
```
  - isAuthenticatedOwnerPassword
```
protected boolean isAuthenticatedOwnerPassword()
```
  - setAuthenticatedOwnerPassword
```
protected void setAuthenticatedOwnerPassword(boolean authenticatedOwnerPassword)
```
  - getValue
```
public java.lang.Object getValue(java.lang.Object key)
```
    Gets any dictionary key specified by the key parameter.
    
    Parameters:
    
    key - named key to retrieve from dictionary.
    
    Returns:
    
    return keys value if found; null, otherwise.
  - toString
```
public java.lang.String toString()
```
    Description copied from class: Dictionary
    
    Returns a summary of the dictionary entries.
    
    Overrides:
    
    toString in class Dictionary
    
    Returns:
    
    dictionary values.

Class EncryptionDictionary

Field Summary

Fields inherited from class org.icepdf.core.pobjects.Dictionary

Constructor Summary

Method Summary

Methods inherited from class org.icepdf.core.pobjects.Dictionary

Methods inherited from class java.lang.Object

Field Detail

FILTER_KEY

SUB_FILTER_KEY

V_KEY

LENGTH_KEY

R_KEY

O_KEY

U_KEY

P_KEY

CF_KEY

STMF_KEY

STRF_KEY

EEF_KEY

OE_KEY

UE_KEY

PERMS_KEY

ENCRYPT_METADATA_KEY

Constructor Detail

EncryptionDictionary

Method Detail

getFileID

getPreferredSecurityHandlerName

getPreferredSecurityHandlerSubName

getVersion

getKeyLength

getRevisionNumber

getBigO

getBigU

getPermissions

getCryptFilter

getStmF

getStrF

getEEF

getBigOE

getBigUE

getPerms

isEncryptMetaData

isAuthenticatedUserPassword

setAuthenticatedUserPassword

isAuthenticatedOwnerPassword

setAuthenticatedOwnerPassword

getValue

toString