com.icesoft.pdf.pobjects.security
Class EncryptionDictionary

java.lang.Object
  com.icesoft.pdf.pobjects.Dictionary
      com.icesoft.pdf.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 inherited from class com.icesoft.pdf.pobjects.Dictionary

entries, inited, library

Constructor Summary

EncryptionDictionary(Library lib, Hashtable encryptionDictionary, Vector fileID)
Creates a new Encryption Dictionary object.

Method Summary

String	getBigO() Gets the 32-byte string used for verifying the owner password.
String	getBigU() Gets the 32-byte string used for verifying the user password.
Hashtable	getEntries() Gets all the dictionary properties.
Vector	getFileID() Gets the document's File ID.
int	getKeyLength() Gets the length of the encryption key, in bits.
String	getPerferredSecurityHandlerName() Gets the preferred security handler name.
String	getPerferredSecurityHandlerSubName() Gets the preferred security handler sub-name.
int	getPermissions() Gets the integer flag which specifies the operation permitted when the document is opened with user access.
int	getRevisionNumber() Gets the revision number of the standard security handler.
Object	getValue(Object key) Gets any dictionary key specified by the key parameter.
int	getVersion() Gets the code specifying the algorithm to be used in encrypting and decrypting the document
String	toString() Returns a summary of the dictionary entries.

Methods inherited from class com.icesoft.pdf.pobjects.Dictionary

getFloat, getInt, getLibrary, getNumber, getObject, getPObjectReference, init, setPObjectReference

Methods inherited from class java.lang.Object

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

Constructor Detail

EncryptionDictionary

public EncryptionDictionary(Library lib,
                            Hashtable encryptionDictionary,
                            Vector 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 Vector getFileID()

Gets the document's File ID.

Returns:

vector containing two values that represent the file ID

getPerferredSecurityHandlerName

public String getPerferredSecurityHandlerName()

Gets the preferred security handler name.

Returns:

handler name.

getPerferredSecurityHandlerSubName

public String getPerferredSecurityHandlerSubName()

Gets the preferred security handler sub-name.

Returns:

handler sub-name.

getVersion

public int getVersion()

Gets the code specifying the algorithm to be used in encrypting and decrypting the document

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 String getBigO()

Gets the 32-byte string used for verifying the owner password.

Returns:

32-byte string representing the key O.

getBigU

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

getValue

public Object getValue(Object key)

Gets any dictionary key specified by the key parameter.

Parameters:

key - named key to retreive from dictionary.

Returns:

return keys value if found; null, otherwise.

getEntries

public Hashtable getEntries()

Gets all the dictionary properties.

Overrides:

getEntries in class Dictionary

Returns:

named based hash of all encryption properties.

toString

public String toString()

Description copied from class: Dictionary

Returns a summary of the dictionary entries.

Overrides:

toString in class Dictionary

Returns:

dictionary values.