org.icepdf.core.pobjects.security
Class EncryptionDictionary

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

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

EncryptionDictionary(Library lib, java.util.HashMap encryptionDictionary, java.util.List fileID)
Creates a new Encryption Dictionary object.

Method Summary

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.HashMap	getEntries() Gets all the dictionary properties.
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

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 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.

getEntries

public java.util.HashMap getEntries()

Gets all the dictionary properties.

Overrides:

getEntries in class Dictionary

Returns:

named based hash of all encryption properties.

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.