PDF Reference sixth edition, Adobe Portable Document Format Version 1.7 (book 2) — page 4
723
SECTION 8.6
Interactive Forms
Example 8.20
1 0 obj
XFA entry in interactive form dictionary
<< /XFA [(xdp:xdp) 10 0 R
XFA resource specified as individual packets
(template) 11 0 R
(datasets) 12 0 R
(config) 13 0 R
(/xdp:xdp) 14 0 R ]
>>
endobj
10 0 obj
stream
<xdp:xdp xmlns:xdp="http://ns.adobe.com/xdp/">
endstream
11 0 obj
stream
<template xmlns="http://www.xfa.org/schema/xfa-template/2.4/">
...remaining contents of template packet...
</template>
endstream
12 0 obj
stream
<xfa:datasets xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">
...contents of datasets packet...
</xfa:datasets>
endstream
13 0 obj
stream
<config xmlns="http://www.xfa.org/schema/xci/1.0/">
...contents of config node of XFA Data Package...
<config>
endstream
14 0 obj
stream
</xdp:xdp>
endstream
724
CHAPTER 8
Interactive Features
Example 8.21
1 0 obj
XFA entry in interactive form dictionary
<< /XFA 10 0 R >>
endobj
10 0 obj
stream
<xdp:xdp xmlns:xdp="http://ns.adobe.com/xdp/">
<template xmlns="http://www.xfa.org/schema/xfa-template/2.4/">
...remaining contents of template packet...
</template>
<xfa:datasets xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">
...contents of datasets packet...
</xfa:datasets>
<config xmlns="http://www.xfa.org/schema/xci/1.0/">
...contents of config node of XFA Data Package...
<config>
</xdp:xdp>
endstream
endobj
When an XFA entry is present in an interactive form dictionary, the XFA resource
provides most of the information about the form; in particular, all form-related
events such as calculations and validations. The other entries in the interactive
form dictionary must be consistent with the information in the XFA resource.
When creating or modifying a PDF file with an XFA resource, applications
should follow these guidelines:
• PDF interactive form field objects must be present for each field specified in
the XFA resource. The XFA field values must be consistent with the corre-
sponding V entries of the PDF field objects.
• The XFA Scripting Object Model (SOM) specifies a naming convention that
must be used to connect interactive form field names with field names in the
XFA resource. Information about this model is available in the XFA Specifica-
tion, version 2.2 (see the Bibliography).
• No A or AA entries (see Table 8.15) should be present in the annotation dictio-
naries of fields that also have actions specified by the XFA resource. The behav-
ior of a field whose actions are specified in both ways is undefined.
725
SECTION 8.7
Digital Signatures
8.7
Digital Signatures
A digital signature (PDF 1.3) can be used to authenticate the identity of a user and
the document’s contents. It stores information about the signer and the state of
the document when it was signed. The signature may be purely mathematical,
such as a public/private-key encrypted document digest, or it may be a biometric
form of identification, such as a handwritten signature, fingerprint, or retinal
scan. The specific form of authentication used is implemented by a plug-in signa-
ture handler. Third-party handler writers are encouraged to register their handler
names with Adobe; see Appendix E.
Signature information is contained in a signature dictionary, whose entries are
listed in Table 8.102. Signature handlers can use or omit those entries that are
marked optional in the table but are encouraged to use them in a standard way if
they are used at all. In addition, signature handlers may add private entries of
their own. To avoid name duplication, it is suggested that the keys for all such pri-
vate entries be prefixed with the registered handler name followed by a period ( . ).
Signatures are created by computing a digest of the data (or part of the data) in a
document, and storing the digest in the document. To verify the signature, the di-
gest is recomputed and compared with the one stored in the document. Differ-
ences in the digest values indicate that modifications have been made since the
document was signed.
There are two defined techniques for computing a reproducible digest of the con-
tents of all or part of a PDF file:
• A byte range digest is computed over a range of bytes in the file, indicated by the
the ByteRange entry in the signature dictionary. This range is typically the en-
tire file, including the signature dictionary but excluding the signature value it-
self (the Contents entry). When a byte range digest is present, all values in the
signature dictionary are required to be direct objects. See implementation note
139 in Appendix H.
• An object digest (PDF 1.5) is computed by selectively walking a subtree of ob-
jects in memory, beginning with the referenced object, which is typically the
root object. The resulting digest, along with information about how it was com-
puted, is placed in a signature reference dictionary, whose entries are listed in
Table 8.103. The TransformMethod entry specifies the general method used to
compute the digest, and the TransformParams entry specifies the variable por-
726
CHAPTER 8
Interactive Features
tion of the computation. Transform methods are described in detail in Section
8.7.1, “Transform Methods.”
A PDF document may contain the following standard types of signatures:
• One or more document (or ordinary) signatures. These signatures appear in sig-
nature form fields (see “Signature Fields” on page 695). The signature dictio-
nary corresponding to each signature is the value of the form field (as specified
by its V entry). The signature dictionary must contain a ByteRange entry repre-
senting a byte range digest, as described above. A signature is validated by re-
computing the digest and comparing it with the one stored in the signature.
Note: If a signed document is modified and saved by incremental update (see Sec-
tion 3.4.5, “Incremental Updates”), the data corresponding to the byte range of the
original signature is preserved. Therefore, if the signature is valid, it is possible to
recreate the state of the document as it existed at the time of signing.
• At most one MDP (modification detection and prevention) signature (PDF 1.5),
also referred to as an author or certifying signature. The signature dictionary of
an MDP signature must be the value of a signature field and must contain a
ByteRange entry. It may also be referenced from the DocMDP entry in the per-
missions dictionary (see Section 8.7.3, “Permissions”). The signature dictio-
nary must contain a signature reference dictionary (see Table 8.103) that has a
DocMDP transform method. See “DocMDP” on page 731 for information on
how these signatures are created and validated.
A signature dictionary for an MDP or ordinary signature may also have a sig-
nature reference dictionary with a FieldMDP transform method; see “FieldM-
DP” on page 736.
• At most two usage rights signatures (PDF 1.5). Its signature dictionary is refer-
enced from the UR or UR3 (PDF 1.6) entry in the permissions dictionary (not
from a signature field); see Table 8.107. The dictionary must contain a signa-
ture reference dictionary that has a UR transform method. See “UR” on page
733 for information on how these signatures are created and validated.
• The Sig entry in the catalog of an FDF file (see “FDF Catalog” on page 713)
specifies a signature dictionary.
727
SECTION 8.7
Digital Signatures
TABLE 8.102 Entries in a signature dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present,
must be Sig for a signature dictionary.
Filter
name
(Required; inheritable) The name of the preferred signature handler to use
when validating this signature. If the Prop_Build entry is not present, it is also
the name of the signature handler that was used to create the signature. If
Prop_Build is present, it can be used to determine the name of the handler
that created the signature (which is typically the same as Filter but is not re-
quired to be). An application may substitute a different handler when verify-
ing the signature, as long as it supports the specified SubFilter format.
Example signature handlers are Adobe.PPKLite, Entrust.PPKEF, CICI.SignIt,
and VeriSign.PPKVS.
SubFilter
name
(Optional) A name that describes the encoding of the signature value and key
information in the signature dictionary. An application may use any handler
that supports this format to validate the signature.
PDF 1.6 defines the following values for public-key cryptographic signatures:
adbe.x509.rsa_sha1, adbe.pkcs7.detached, and adbe.pkcs7.sha1 (see Section
8.7.2, “Signature Interoperability”). Other values can be defined by third par-
ty developers, subject to the restriction that all names beginning with the
adbe. prefix be reserved for future versions of PDF. All third party names
must be registered with Adobe Systems (see Appendix E).
Contents
byte string
(Required) The signature value. When ByteRange is present, the value is a
hexadecimal string (see “Hexadecimal Strings” on page 56) representing the
value of the byte range digest. If ByteRange is not present, the value is an ob-
ject digest of the signature dictionary, excluding the Contents entry.
For public-key signatures, Contents is commonly either a DER-encoded
PKCS#1 binary data object or a DER-encoded PKCS#7 binary data object.
Cert
array or
(Required when SubFilter is adbe.x509.rsa_sha1) An array of byte strings rep-
byte string
resenting the X.509 certificate chain used when signing and verifying signa-
tures that use public-key cryptography, or a byte string if the chain has only
one entry. The signing certificate must appear first in the array; it is used to
verify the signature value in Contents, and the other certificates are used to
verify the authenticity of the signing certificate.
If SubFilter is adbe.pkcs7.detached or adbe.pkcs7.sha1, this entry is not
used, and the certificate chain must be put in the PKCS#7 envelope in
Contents.
728
CHAPTER 8
Interactive Features
KEY
TYPE
VALUE
ByteRange
array
(Required for all signatures that are part of a signature field and usage rights
signatures referenced from the UR3 entry in the permissions dictionary) An ar-
ray of pairs of integers (starting byte offset, length in bytes) describing the ex-
act byte range for the digest calculation. Multiple discontiguous byte ranges
are used to describe a digest that does not include the signature value (the
Contents entry) itself.
Reference
array
(Optional; PDF 1.5) An array of signature reference dictionaries (see Table
8.103).
Changes
array
(Optional) An array of three integers specifying changes to the document that
have been made between the previous signature and this signature: in this or-
der, the number of pages altered, the number of fields altered, and the num-
ber of fields filled in. (See implementation note 139 in Appendix H.)
Note: The ordering of signatures is determined by the value of ByteRange. Since
each signature results in an incremental save, later signatures have a greater
length value.
Name
text string
(Optional) The name of the person or authority signing the document. This
value should be used only when it is not possible to extract the name from
the signature; for example, from the certificate of the signer.
M
date
(Optional) The time of signing. Depending on the signature handler, this may
be a normal unverified computer time or a time generated in a verifiable way
from a secure time server.
This value should be used only when the time of signing is not available in
the signature; for example, a time stamp can be embedded in a PKCS#7 bina-
ry data object (see “PKCS#7 Signatures” on page 738).
Location
text string
(Optional) The CPU host name or physical location of the signing.
Reason
text string
(Optional) The reason for the signing, such as ( I agree… ).
ContactInfo
text string
(Optional) Information provided by the signer to enable a recipient to contact
the signer to verify the signature; for example, a phone number.
R
integer
(Optional) The version of the signature handler that was used to create the
signature.
Note: Beginning with PDF 1.5, this entry is deprecated, and the information
should be stored in the Prop_Build dictionary.
729
SECTION 8.7
Digital Signatures
KEY
TYPE
VALUE
V
integer
(Optional; PDF 1.5) The version of the signature dictionary format. It corre-
sponds to the usage of the signature dictionary in the context of the value of
SubFilter. The value is 1 if the Reference dictionary is considered critical to
the validation of the signature.
Default value: 0.
Prop_Build
dictionary
(Optional; PDF 1.5) A dictionary that can be used by a signature handler to
record information that captures the state of the computer environment used
for signing, such as the name of the handler used to create the signature, soft-
ware build date, version, and operating system.
Adobe publishes a separate specification, the PDF Signature Build Dictionary
Specification for Acrobat 6.0 that provides implementation guidelines for the
use of this dictionary.
Prop_AuthTime
integer
(Optional; PDF 1.5) The number of seconds since the signer was last authen-
ticated. It is intended to be used in claims of signature repudiation. It should
be omitted if the value is unknown.
Prop_AuthType
name
(Optional; PDF 1.5) The method used to authenticate the signer. It is intend-
ed to be used in claims of signature repudiation. Valid values include PIN,
Password, and Fingerprint.
Note: The entries in the signature dictionary can be conceptualized as being in dif-
ferent dictionaries; they are in one dictionary for historical and cryptographic rea-
sons. The categories are signature properties
(R, M, Name, Reason, Location,
Prop_Build, Prop_AuthTime, and Prop_AuthType); key information (Cert and por-
tions of Contents when the signature value is a PKCS#7 object); reference
(Reference and ByteRange); and signature value (Contents when the signature val-
ue is a PKCS#1 object).
730
CHAPTER 8
Interactive Features
TABLE 8.103 Entries in a signature reference dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if
present, must be SigRef for a signature reference dictionary.
TransformMethod
name
(Required) The name of the transform method (see Section 8.7.1,
“Transform Methods”) that guides the object digest computation or
modification analysis that takes place when the signature is validat-
ed. Valid values are:
DocMDP Used to detect modifications to a document relative
to a signature field that is signed by the originator of
a document; see “DocMDP” on page 731.
UR
Used to detect modifications to a document that
would invalidate a signature in a rights-enabled doc-
ument; see “UR” on page 733.
FieldMDP Used to detect modifications to a list of form fields
specified in TransformParams; see “FieldMDP” on
page 736.
Identity
Used when signing a single object, which is specified
by the value of Data in the signature reference dic-
tionary (see Table 8.103). This transform method
supports signing of FDF files. See “Identity” on page
737 for details.
TransformParams
dictionary
(Optional) A dictionary specifying transform parameters (variable
data) for the transform method specified by TransformMethod.
Each method except Identity takes its own set of parameters. See
each of the sections specified above for details on the individual
transform parameter dictionaries
Data
(various)
(Required when TransformMethod is FieldMDP or Identity) An indi-
rect reference to the object in the document over which the digest
was computed or upon which the object modification analysis
should be performed. For transform methods other than FieldMDP
and Identity, this object is implicitly defined.
DigestMethod
name
(Optional) A name identifying the algorithm to be used when com-
puting the digest. Valid values are MD5 and SHA1. (See implemen-
tation note 144 in Appendix H.) Default value: MD5.
731
SECTION 8.7
Digital Signatures
KEY
TYPE
VALUE
DigestValue
string
(Required in some situations) When present, the computed value of
the digest. See Section 8.7.1, “Transform Methods, for details on
when this entry is required.
DigestLocation
array
(Required when DigestValue is required and TransformMethod is
FieldMDP or DocMDP) An array of two integers specifying the loca-
tion in the PDF file of the DigestValue string. The integers represent
the starting offset and length in bytes, respectively.
This entry is required when DigestValue is written directly to the
PDF file, bypassing any encryption that has been performed on the
document. When specified, the values must be used to read
DigestValue directly from the file during validation.
8.7.1
Transform Methods
Transform methods, along with transform parameters, determine which objects
are included and excluded in object digest computation or revision comparison.
The following sections discuss the types of transform methods, their transform
parameters, and when they are used. Appendix I, “Computation of Object Di-
gests,” describes in detail the algorithm for computing object digests.
Note: All transform methods exclude the signature dictionary from the object digest.
DocMDP
The DocMDP transform method is used to detect modifications relative to a sig-
nature field that is signed by the author of a document (the person applying the
first signature). A document can contain only one signature field that contains a
DocMDP transform method; it must be the first signed field in the document. It
enables the author to specify what changes are permitted to be made the docu-
ment and what changes invalidate the author’s signature.
As discussed earlier, “MDP” stands for modification detection and prevention.
Such signatures enable detection of disallowed changes specified by the author. In
addition, disallowed changes can also be prevented when the signature dictionary
is referred to by the DocMDP entry in the permissions dictionary (see Section
8.7.3, “Permissions”).
732
CHAPTER 8
Interactive Features
Note: When creating an author signature, applications are encouraged to create a
legal attestation dictionary (see Section 8.7.4, “Legal Content Attestations”) that
specifies all content that might result in unexpected rendering of the document con-
tents, along with the author’s attestation to such content. This dictionary can be
used to establish an author’s intent if the integrity of the document is questioned.
The P entry in the DocMDP transform parameters dictionary (see Table 8.104) in-
dicates the author’s specification of which changes to the document will invali-
date the signature. (These changes to the document are also prevented if the
signature dictionary is referred to from the DocMDP entry in the permissions dic-
tionary.) A value of 1 for P indicates that the document is intended to be final;
that is, any changes invalidate the signature. The values 2 and 3 permit modifica-
tions that are appropriate for form field or comment workflows.
The DocMDP object digest is computed over a subset of the PDF objects in the
document. Specifically, this subset consists of the objects that are not permitted
to be modified, directly or indirectly, as specified by the transform parameters
dictionary. Appendix I describes the object digest computation.
Validating MDP signatures
To validate an MDP signature, an application first verifies the byte range digest.
Next, it verifies that any modifications that have been made to the document are
permitted by the transform parameters by using one of the following techniques:
• PDF 1.5 required the calculated value of the object digest at the time of signing
to be stored in the DigestValue entry in the signature reference dictionary (see
Table 8.103). Therefore, an application can compare this entry to its calculated
object digest when validating. If the values are different, the signature is invalid.
• In PDF 1.6, the DigestValue entry is not required. Once the byte range digest is
validated, the portion of the document specified by the ByteRange entry in the
signature dictionary (see Table 8.102) is known to correspond to the state of the
document at the time of signing. Therefore, applications can compare the
signed and current versions of the document to see whether there have been
modifications to any objects that are not permitted by the transform parame-
ters. See implementation note 141 in Appendix H.
733
SECTION 8.7
Digital Signatures
TABLE 8.104 Entries in the DocMDP transform parameters dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
TransformParams for a transform parameters dictionary.
P
number
(Optional) The access permissions granted for this document. Valid values are:
1
No changes to the document are permitted; any change to the docu-
ment invalidates the signature.
2
Permitted changes are filling in forms, instantiating page templates,
and signing; other changes invalidate the signature.
3
Permitted changes are the same as for 2, as well as annotation creation,
deletion, and modification; other changes invalidate the signature.
Default value: 2.
V
name
(Optional) The DocMDP transform parameters dictionary version. The only valid val-
ue is 1.2. (Note that this value is a name object, not a number.) (See implementation
note 145 in Appendix H.) Default value: 1.2.
UR
The UR transform method is used to detect changes to a document that would in-
validate a usage rights signature, which is referred to from the UR or UR3 entry in
the permissions dictionary (see Section 8.7.3, “Permissions). Usage rights signa-
tures are used to enable additional interactive features that are not available by
default in a particular viewer application (such as Adobe Reader). The signature
is used to validate that the permissions have been granted by a bonafide granting
authority. The transform parameters dictionary (see Table 8.105) specifies the ad-
ditional rights that are enabled if the signature is valid. If the signature is invalid
because the document has been modified in a way that is not permitted or the
identity of the signer is not granted the extended permissions, additional rights
are not granted.
Adobe Systems grants permissions, for example, to enable additional features in
Adobe Reader, using public-key cryptography. It uses certificate authorities to is-
sue public key certificates to document creators with which it has entered into a
business relationship. Adobe Reader verifies that the rights-enabling signature
uses a certificate from an Adobe-authorized certificate authority. Other PDF
viewer applications are free to use this same mechanism for their own purposes.
734
CHAPTER 8
Interactive Features
Validation of a usage rights signature depends on whether the signature dictio-
nary is referenced from the UR or UR3 entry in the permissions dictionary (See
implementation note 142 in Appendix H):
• UR: At the time of signing, the application computes the object digest over a
subset of the PDF objects in the document; that is, the objects that are not
modified, directly or indirectly, by permissible operations, as specified by the
transform parameters dictionary. Appendix I describes the object digest com-
putation. The calculated value of this digest is stored in the DigestValue entry
in the signature reference dictionary (see Table 8.103). An application can com-
pare this entry to its calculated object digest when validating. If the values are
different, the signature is invalid.
Note: The use of UR is not recommended because of the complex (and hence prone
to errors) algorithm. Instead, the UR3 (see below) algorithm should be used.
• UR3 (PDF 1.6): The ByteRange entry in the signature dictionary (see Table
8.102) is required to be present. First, the application verifies the byte range di-
gest to determine whether the portion of the document specified by ByteRange
corresponds to the state of the document at the time of signing. Next, the appli-
cation examines the current version of the document to see whether there have
been modifications to any objects that are not permitted by the transform pa-
rameters.
TABLE 8.105 Entries in the UR transform parameters dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
TransformParams for a transform parameters dictionary.
Document
array
(Optional) An array of names specifying additional document-wide usage rights for
the document. The only defined value is FullSave, which permits a user to save the
document along with modified form and/or annotation data. (See implementation
note 143 in Appendix H.)
Msg
text
(Optional) A text string that can be used to specify any arbitrary information, such as
string
the reason for adding usage rights to the document.
V
name
(Optional) The UR transform parameters dictionary version. The only valid value is
2.2. If an unknown version is present, no rights are enabled. (Note that this value is a
name object, not a number.) (See implementation note 145 in Appendix H.) Default
value: 2.2.
735
SECTION 8.7
Digital Signatures
KEY
TYPE
VALUE
Annots
array
(Optional) An array of names specifying additional annotation-related usage rights
for the document. Valid names in PDF 1.5 and later are Create, Delete, Modify, Copy,
Import, and Export, which permit the user to perform the named operation on anno-
tations.
The following names were added in PDF 1.6. They are permitted only when the signa-
ture dictionary is referenced from the UR3 entry of the permissions dictionary (see
Table 8.107):
Online
Permits online commenting; that is, the ability to upload or
download markup annotations from a server.
SummaryView
Permits a user interface to be shown that summarizes the
comments (markup annotations) in a document.
Form
array
(Optional) An array of names specifying additional form-field-related usage rights for
the document. Valid names in PDF 1.5 are:
FillIn
Permits the user to save a document on which form fill-in
has been done.
Import
Permits the user to import form data files in FDF, XFDF
and text (CSV/TSV) formats.
Export
Permits the user to export form data files as FDF or XFDF.
SubmitStandalone
Permits the user to submit form data when the document is
not open in a Web browser.
SpawnTemplate
Permits new pages to be instantiated from named page tem-
plates.
The following names were added in PDF 1.6. They are permitted only when the signa-
ture dictionary is referenced from the UR3 entry of the permissions dictionary; see
Table 8.107 (however, see FormEx below):
BarcodePlaintext
Permits text form field data to be encoded as a plaintext
two-dimensional barcode.
Online
(PDF 1.6) Permits the use of forms-specific online mecha-
nisms such as SOAP or Active Data Object.
FormEx
array
(Optional; permitted only when the signature dictionary is referenced from the UR entry
of the permissions dictionary; PDF 1.5) An array of names specifying additional form-
field-related usage rights. The only valid name is BarcodePlaintext, which permits text
form field data to be encoded as a plaintext two-dimensional barcode.
736
CHAPTER 8
Interactive Features
KEY
TYPE
VALUE
Signature
array
(Optional) An array of names specifying additional signature-related usage rights for
the document. The only defined value is Modify, which permits a user to apply a digi-
tal signature to an existing signature form field or clear a signed signature form field.
EF
array
(Optional; PDF 1.6) An array of names specifying additional usage rights for named
embedded files in the document. Valid names are Create, Delete, Modify, and Import,
which permit the user to perform the named operation on named embedded files.
P
boolean
(Optional; PDF 1.6) If true, permissions for the document should be restricted in all
consumer applications to those permissions granted by Adobe Reader, while allowing
permissions for rights enabled by other entries in this dictionary. Default value: false.
FieldMDP
The FieldMDP transform method computes an object digest over a list of form
field objects and is used to detect changes to the values of those form fields. The
entries in its transform parameters dictionary are listed in Table 8.106.
TABLE 8.106 Entries in the FieldMDP transform parameters dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
TransformParams for a transform parameters dictionary.
Action
name
(Required) A name that, along with the Fields array, describes which form fields are
included in the object digest (and hence do not permit changes after the signature is
applied). Valid values are:
All
All form fields.
Include
Only those form fields that are specified in Fields.
Exclude
Only those form fields that are not specified in Fields.
Fields
array
(Required if Action is Include or Exclude) An array of text strings containing field
names.
V
name
(Optional) The transform parameters dictionary version. The value for PDF 1.5 and
later is 1.2. (Note that this value is a name object, not a number.) (See implementation
note 145 in Appendix H.) Default value: 1.2.
737
SECTION 8.7
Digital Signatures
In documents intended for form field workflows, the following occurs:
• The author specifies that form fields can be filled in without invalidating the
author’s signature. The P entry of the DocMDP transform parameters dictionary
is set to either 2 or 3 (see Table 8.104).
• The author can also specify that after a specific recipient has signed the docu-
ment, any modifications to specific form fields should invalidate that recipient’s
signature. There is a separate signature field for each designated recipient, each
having an associated signature field lock dictionary (see Table 8.82) specifying
the form fields that should be locked for that user.
• When the recipient signs the field, the signature, signature reference, and trans-
form parameters dictionaries are created. The Action and Fields entries in the
transform parameters dictionary are copied from the corresponding fields in
the signature field lock dictionary.
Note: This copying is done because all objects in a signature dictionary must be
direct objects if the dictionary contains a byte range signature. (Even though
FieldMDP signatures are object signatures, any signature dictionary referred to
from a signature field must also have a byte range signature.) Therefore, the
transform parameters dictionary cannot reference the signature field lock dictio-
nary indirectly.
The object digest is computed over all the form fields specified by the transform
parameters dictionary, sorted in alphabetical order (see Appendix I for details).
The specified form fields are locked to prevent changes by marking them read-
only. Any changes to the form fields can be detected when the recipient’s signa-
ture is verified.
FieldMDP signatures are validated in a similar manner to DocMDP signatures. See
“Validating MDP signatures” on page 732 for details.
Identity
The Identity transform method is used when computing an object digest that is
all-inclusive; that is, no objects are excluded. The entire object tree is walked,
starting with the object specified by Data in the signature reference dictionary
(see Table 8.103). Any changes to the contents of the object invalidate the signa-
ture. This method is used to support the signing of FDF files. The FDF catalog is
the object over which the digest is calculated.
738
CHAPTER 8
Interactive Features
8.7.2
Signature Interoperability
It is intended that PDF consumer applications allow interoperability between sig-
nature handlers; that is, a PDF file signed with a handler from one vendor must
be able to be validated with a handler from a different vendor.
The SubFilter entry in the signature dictionary specifies the encoding of the sig-
nature value and key information, and the Filter entry specifies the preferred han-
dler to use to validate the signature. Handlers specify the SubFilter encodings
they support; therefore, handlers other than the preferred handler can be used to
validate the signature if necessary or desired.
There are several defined values for the SubFilter entry, all based on public-key
cryptographic standards published by RSA Security and also as part of the stan-
dards issued by the Internet Engineering Task Force (IETF) Public Key Infra-
structure (PKIX) working group; see the Bibliography for references.
PKCS#1 Signatures
The PKCS#1 standard supports several public-key cryptographic algorithms and
digest methods, including RSA encryption, DSA signatures, and SHA-1 and MD5
digests (see the Bibliography for references). For signing PDF files using PKCS#1,
the only recommended value of SubFilter is adbe.x509.rsa_sha1, which uses the
RSA encryption algorithm and SHA-1 digest method. The certificate chain of the
signer is stored in the Cert entry.
PKCS#7 Signatures
When PKCS#7 signatures are used, the value of Contents is a DER-encoded
PKCS#7 binary data object containing the signature. SubFilter can take one of the
following values:
• adbe.pkcs7.detached: No data is encapsulated in the PKCS#7 signed-data field.
• adbe.pkcs7.sha1: The SHA1 digest of the byte range is encapsulated in the
PKCS#7 signed-data field with ContentInfo of type Data.
The PKCS#7 object must conform to the PKCS#7 specification in Internet RFC
2315, PKCS #7: Cryptographic Message Syntax, Version 1.5 (see the Bibliography).
739
SECTION 8.7
Digital Signatures
At minimum, it must include the signer’s X.509 signing certificate. This certifi-
cate is used to verify the signature value in Contents.
The PKCS#7 object may optionally contain the following attributes:
• Time stamp information as an unsigned attribute (PDF 1.6): The timestamp to-
ken must conform to RFC 3161 and must be computed and embedded into the
PKCS#7 object as described in Appendix A of RFC 3161.
• Revocation information as an signed attribute (PDF 1.6): This attribute can in-
clude all the revocation information that is necessary to carry out revocation
checks for the signer's certificate and its issuer certificates.
• One or more issuer certificates from the signer’s trust chain (PDF 1.6); see im-
plementation note 146 in Appendix H.
• One or more RFC 3281 attribute certificates associated with the signer certifi-
cate (PDF 1.7).
Revocation Information
The following object identifier identifies Adobe's revocation information at-
tribute:
adbe-revocationInfoArchival OBJECT IDENTIFIER ::=
{ adbe(1.2.840.113583) acrobat(1) security(1) 8 }
The value of the revocation information attribute can include any of the following
data types:
• Certificate Revocation Lists (CRLs), described in RFC 3280 (see the Bibliogra-
phy): CRLs are generally large and therefore not recommended to be embed-
ded in the PKCS#7 object.
• Online Certificate Status Protocol (OCSP) Responses, described in RFC 2560,
X.509 Internet Public Key Infrastructure Online Certificate Status Protocol—
OCSP (see the Bibliography): These are generally small and constant in size and
are the suggested data type to be included in the PKCS#7 object.
• Custom revocation information: The format is not prescribed by this specifica-
tion, other than that it be encoded as an OCTET STRING. The application should
be able to determine the type of data contained within the OCTET STRING by
looking at the associated OBJECT IDENTIFIER.
740
CHAPTER 8
Interactive Features
Adobe's Revocation Information attribute value has ASN.1 type
RevocationInfoArchival:
RevocationInfoArchival ::= SEQUENCE {
crl
[0] EXPLICIT SEQUENCE of CRLs, OPTIONAL
ocsp
[1] EXPLICIT SEQUENCE of OCSP Responses, OPTIONAL
otherRevInfo [2] EXPLICIT SEQUENCE of OtherRevInfo, OPTIONAL
}
OtherRevInfo ::= SEQUENCE {
Type OBJECT IDENTIFIER
Value OCTET STRING
}
For byte range signatures, Contents is a hexadecimal string with “<” and “>” de-
limiters. It must fit precisely in the space between the ranges specified by
ByteRange. Since the length of PKCS#7 objects is not entirely predictable, it is of-
ten necessary to pad the value of Contents with zeros at the end of the string (be-
fore the “>” delimiter) before writing the PKCS#7 to the allocated space in the file.
The most common format for encoding signature values is adbe.pkcs7.detached.
This encoding allows the most options in terms of algorithm use. The following
table shows the algorithms supported for the various SubFilter values.
SubFilter value
a
adbe.pkcs7.detached
adbe.pkcs7.sha1
adbe.x509.rsa.sha1
Message Digest
SHA1 (PDF 1.3)
SHA1 (PDF 1.3)b
SHA1 (PDF 1.3)
SHA256 (PDF 1.6)
SHA256 (PDF 1.6)
SHA384 (PDF 1.7)
SHA384 (PDF 1.7)
SHA512 (PDF 1.7)
SHA512 (PDF 1.7)
RIPEMD160 (PDF 1.7)
RIPEMD160 (PDF 1.7)
RSA Algorithm Support Up to 1024-bit (PDF 1.3)
See adbe.pkcs7.detached See
Up to 2048-bit (PDF 1.5)
adbe.pkcs7.detached
Up to 4096-bit (PDF 1.5)
DSA Algorithm Support Up to 4096-bits (PDF 1.6) See adbe.pkcs7.detached No
a. Despite the appearance of sha1 in the name of this SubFilter value, supported encodings are not limited to the
SHA1 algorithm. The PKCS#1 object contains an identifier that indicates which algorithm is used.
b. Other digest algorithms may be used to digest the signed-data field; however, SHA1 is always used to digest the
data that is being signed.
741
SECTION 8.7
Digital Signatures
8.7.3
Permissions
The Perms entry in the document catalog (see Table 3.25) specifies a permissions
dictionary (PDF 1.5). Each entry in this dictionary (see Table 8.107 for the cur-
rently defined entries) specifies the name of a permission handler that controls ac-
cess permissions for the document. These permissions are similar to those defined
by security handlers (see Table 3.20 on page 123) but do not require that the docu-
ment be encrypted. For a permission (for example, the ability to fill in form fields)
to be actually granted for a document, it must be allowed by each permission han-
dler that is present in the permissions dictionary as well as by the security handler.
TABLE 8.107 Entries in a permissions dictionary
KEY
TYPE
VALUE
DocMDP
dictionary
(Optional) An indirect reference to a signature dictionary (see Table 8.102). This
dictionary must contain a Reference entry that is a signature reference dictionary
(see Table 8.103) that has a DocMDP transform method (see “DocMDP” on page
731) and corresponding transform parameters.
If this entry is present, consumer applications should enforce the permissions spec-
ified by the P attribute in the DocMDP transform parameters dictionary and should
also validate the corresponding signature based on whether any of these permis-
sions have been violated.
UR
dictionary
(Optional) A signature dictionary that is used to specify and validate additional ca-
pabilities (usage rights) granted for this document; that is, the enabling of interac-
tive features of the viewer application that are not available by default.
For example, Adobe Reader does not permit saving documents by default, but Ado-
be Systems may grant permissions that enable saving in Adobe Reader for specific
documents. The signature is used to validate that the permissions have been granted
by Adobe Systems.
The signature dictionary must contain a Reference entry that is a signature refer-
ence dictionary that has a UR transform method (see “UR” on page 733). The trans-
form parameter dictionary for this method indicates which additional permissions
should be granted for the document. If the signature is valid, the Adobe Reader al-
lows the specified permissions for the document, in addition to the application’s de-
fault permissions.
The signature dictionary must not contain a ByteRange entry.
UR3
dictionary
(Optional; PDF 1.6) A signature dictionary that specifies and validates usage rights.
The description of the UR entry above applies to UR3, except that the signature dic-
tionary must contain a ByteRange entry. See “UR” on page 733 for details.
742
CHAPTER 8
Interactive Features
8.7.4
Legal Content Attestations
The PDF language provides a number of capabilities that can make the rendered
appearance of a PDF document vary. These capabilities could potentially be used
to construct a document that misleads the recipient of a document, intentionally
or unintentionally. These situations are relevant when considering the legal im-
plications of a signed PDF document.
Therefore, it is necessary to have a mechanism by which a document recipient
can determine whether the document can be trusted. The primary method is to
accept only documents that contain author signatures (one that has a DocMDP
signature that defines what is permitted to change in a document; see “DocMDP”
on page 731).
When creating author signatures, applications should also create a legal attesta-
tion dictionary, whose entries are shown in Table 8.108. This dictionary is the val-
ue of the Legal entry in the document catalog (see Table 3.25). Its entries specify
all content that may result in unexpected rendering of the document contents.
The author may provide further clarification of such content by means of the
Attestation entry. Reviewers should establish for themselves that they trust the
author and contents of the document. In the case of a legal challenge to the docu-
ment, any questionable content can be reviewed in the context of the information
in this dictionary.
TABLE 8.108 Entries in a legal attestation dictionary
KEY
TYPE
VALUE
JavaScriptActions
integer
(Optional) The number of JavaScript actions found in the document (see
“JavaScript Actions” on page 709).
LaunchActions
integer
(Optional) The number of launch actions found in the document (see
“Launch Actions” on page 659).
URIActions
integer
(Optional) The number of URI actions found in the document (see “URI
Actions” on page 662).
MovieActions
integer
(Optional) The number of movie actions found in the document (see “Mov-
ie Actions” on page 664).
SoundActions
integer
(Optional) The number of sound actions found in the document (see
“Sound Actions” on page 663).
HideAnnotationActions integer
(Optional) The number of hide actions found in the document (see “Hide
Actions” on page 665).
743
SECTION 8.7
Digital Signatures
KEY
TYPE
VALUE
GoToRemoteActions
integer
(Optional) The number of remote go-to actions found in the document (see
“Remote Go-To Actions” on page 655).
AlternateImages
integer
(Optional) The number of alternate images found in the document (see “Al-
ternate Images” on page 347)
ExternalStreams
integer
(Optional) The number of external streams found in the document.
TrueTypeFonts
integer
(Optional) The number of TrueType fonts found in the document (see
“TrueType Fonts” on page 418).
ExternalRefXobjects
integer
(Optional) The number of reference XObjects found in the document (see
“Reference XObjects” on page 361).
ExternalOPIdicts
integer
(Optional) The number of OPI dictionaries found in the document (see
“Open Prepress Interface (OPI)” on page 978).
NonEmbeddedFonts
integer
(Optional) The number of non-embedded fonts found in the document (see
Section 5.8, “Embedded Font Programs”)
DevDepGS_OP
integer
(Optional) The number of references to the graphics state parameter OP
found in the document (see Table 4.8).
DevDepGS_HT
integer
(Optional) The number of references to the graphics state parameter HT
found in the document (see Table 4.8).
DevDepGS_TR
integer
(Optional) The number of references to the graphics state parameter TR
found in the document (see Table 4.8).
DevDepGS_UCR
integer
(Optional) The number of references to the graphics state parameter UCR
found in the document (see Table 4.8).
DevDepGS_BG
integer
(Optional) The number of references to the graphics state parameter BG
found in the document (see Table 4.8).
DevDepGS_FL
integer
(Optional) The number of references to the graphics state parameter FL
found in the document (see Table 4.8).
Annotations
integer
(Optional) The number of annotations found in the document (see Section
8.4, “Annotations”).
OptionalContent
boolean
(Optional) true if optional content is found in the document (see Section
4.10, “Optional Content”).
Attestation
text
(Optional) An attestation, created by the author of the document, explain-
string
ing the presence of any of the other entries in this dictionary or the presence
of any other content affecting the legal integrity of the document.
744
CHAPTER 8
Interactive Features
8.8
Measurement Properties
PDF documents, such as those created by CAD software, may contain graphics
that are intended to represent real-world objects. Users of such documents often
require information about the scale and units of measurement of the correspond-
ing real-world objects and their relationship to units in PDF user space.
This information enables users of viewer applications to perform measurements
that yield results in the units intended by the creator of the document. A mea-
surement in this context is the result of a canonical function that takes as input a
set of n coordinate pairs
{
(
x0,y0
),
…,(xn-1,yn-1
)}
and produces a single number as output depending on the type of measurement.
For example, distance measurement is equivalent to
n-2
+
(
yi – yi+1
)2
∑ (xi – xi + 1)2
i=0
for
n ≥ 2.
Beginning with PDF 1.6, such information may be stored in a measure dictionary
(see Table 8.110). Measure dictionaries provide information about measurement
units associated with a rectangular area of the document known as a viewport.
A viewport (PDF 1.6) is a rectangular region of a page. The optional VP entry in a
page dictionary (see Table 3.27) specifies an array of viewport dictionaries, whose
entries are shown in Table 8.109. Viewports allow different measurement scales
(specified by the Measure entry) to be used in different areas of a page, if necessary.
The dictionaries in the VP array are in drawing order. Since viewports might
overlap, to determine the viewport to use for any point on a page, the dictionaries
in the array are examined, starting with the last one and iterating in reverse, and
the first one whose BBox entry contains the point is chosen.
Note: Any measurement that potentially involves multiple viewports, such as one
specifying the distance between two points, should use the information specified in
the viewport of the first point.
745
SECTION 8.8
Measurement Properties
TABLE 8.109 Entries in a viewport dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; must be Viewport
for a viewport dictionary.
BBox
rectangle
(Required) A rectangle in default user space coordinates specifying the location of
the viewport on the page.
The two coordinate pairs of the rectangle must be specified in normalized form;
that is, lower-left followed by upper-right, relative to the measuring coordinate sys-
tem. This ordering determines the orientation of the measuring coordinate system
(that is, the direction of the positive x and y axes) in this viewport, which may have
a different rotation from the page.
Note: The coordinates of this rectangle are independent of the origin of the measuring
coordinate system, specified in the O entry (see Table 8.111) of the measurement dic-
tionary specified by Measure.
Name
text string
(Optional) A descriptive text string or title of the viewport, intended for use in a
user interface.
Measure
dictionary
(Optional) A measure dictionary (see Table 8.110) that specifies the scale and units
that should apply to measurements taken on the contents within the viewport.
A measure dictionary specifies an alternate coordinate system for a region of a
page. Along with the viewport dictionary, it provides the information needed to
convert coordinates in the page’s coordinate system to coordinates in the measur-
ing coordinate system. The measure dictionary provides information for format-
ting the resulting values into textual form for presentation in a graphical user
interface.
Table 8.110 shows the entries in a measure dictionary. PDF 1.6 defines only a sin-
gle type of coordinate system, a rectilinear coordinate system, specified by the val-
ue RL for the Subtype entry, which is defined as one in which the x and y axes are
perpendicular and have units that increment linearly (to the right and up, respec-
tively). Other subtypes are permitted, providing the flexibility to measure using
other types of coordinate systems.
746
CHAPTER 8
Interactive Features
TABLE 8.110 Entries in a measure dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; must be Measure
for a measure dictionary.
Subtype
name
(Optional) A name specifying the type of coordinate system to use for measuring.
Default value: RL, which specifies a rectilinear coordinate system
Table 8.111 shows the additional entries in a rectilinear measure dictionary. Many
of the entries in this dictionary are number format arrays, which are arrays of
number format dictionaries (see Table 8.112). Each number format dictionary
represents a specific unit of measurement (such as miles or feet). It contains in-
formation about how each unit is expressed in text and factors for calculating the
number of units.
Number format arrays specify all the units that are to be used when expressing a
specific measurement. Each array contains one or more number format dictio-
naries, in descending order of granularity. (For example, a number format dictio-
nary specifying feet should precede one specifying inches.) All the elements in
the array contain text strings that, concatenated together, specify how the units
should be displayed. For example, a measurement of 1.4505 miles might be ex-
pressed as “1.4505 mi”, which would require one number format dictionary for
miles, or as “1 mi 2,378 ft 7 5/8 in”, which would require three dictionaries (for
miles, feet, and inches).
TABLE 8.111 Additional entries in a rectilinear measure dictionary
KEY
TYPE
VALUE
R
text string
(Required) A text string expressing the scale ratio of the drawing in the region corre-
sponding to this dictionary. Universally recognized unit abbreviations should be
used, either matching those of the number format arrays in this dictionary or those
of commonly used scale ratios. For example, a common scale in architectural draw-
ings is “1/4 in = 1 ft”, indicating that 1/4 inches in default user space is equivalent to
1 foot in real-world measurements.
If the scale ratio differs in the x and y directions, both scales should be specified; for
example, “in X 1 cm = 1 m, in Y 1 cm = 30 m”.
747
SECTION 8.8
Measurement Properties
KEY
TYPE
VALUE
X
array
(Required) A number format array for measurement of change along the x axis and,
if Y is not present, along the y axis as well. The first element in the array contains the
scale factor for converting from default user space units to the largest units in the
measuring coordinate system along that axis.
The directions of the x and y axes are in the measuring coordinate system and are
independent of the page rotation. These directions are determined by the BBox en-
try of the containing viewport (see Table 8.109).
Y
array
(Required when the x and y scales have different units or conversion factors) A num-
ber format array for measurement of change along the y axis. The first element in
the array contains the scale factor for converting from default user space units to the
largest units in the measuring coordinate system along the y axis.
D
array
(Required) A number format array for measurement of distance in any direction.
The first element in the array specifies the conversion to the largest distance unit
from units represented by the first element in X. The scale factors from X, Y (if
present) and CYX (if Y is present) are used to convert from default user space to the
appropriate units before applying the distance function.
A
array
(Required) A number format array for measurement of area. The first element in the
array specifies the conversion to the largest area unit from units represented by the
first element in X, squared. The scale factors from X, Y (if present) and CYX (if Y is
present) are used to convert from default user space to the appropriate units before
applying the area function.
T
array
(Optional) A number format array for measurement of angles. The first element in
the array specifies the conversion to the largest angle unit from degrees. The scale
factor from CYX (if present) is used to convert from default user space to the appro-
priate units before applying the angle function.
S
array
(Optional) A number format array for measurement of the slope of a line. The first
element in the array specifies the conversion to the largest slope unit from units rep-
resented by the first element in Y divided by the first element in X. The scale factors
from X, Y (if present) and CYX (if Y is present) are used to convert from default user
space to the appropriate units before applying the slope function.
O
array
(Optional) An array of two numbers specifying the origin of the measurement coor-
dinate system in default user space coordinates. The directions by which x and y in-
crease in value from this origin is determined by the viewport’s BBox entry (see
Table 8.109).
Default value: the first coordinate pair (lower-left corner) of the rectangle specified
by the viewport’s BBox entry.
748
CHAPTER 8
Interactive Features
KEY
TYPE
VALUE
CYX
number
(Optional; meaningful only when Y is present) A factor to convert the largest units
along the y axis to the largest units along the x axis. It is required for some calcula-
tions (distance, area, and angle) where the units must be equivalent; if not specified,
these calculations cannot be performed (which would be the case in situations such
as x representing time and y representing temperature). Other calculations (change
in x, change in y, and slope) do not require this value.
The X and Y entries in a measure dictionary are number format arrays that speci-
fy the units used for measurements in the x and y directions, respectively, and the
ratio between user space units and the specified units. Y is present only when the
x and y measurements are in different units or have different ratios; in this case,
the CYX entry is used to convert y values to x values when appropriate.
TABLE 8.112 Entries in a number format dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; must be
NumberFormat for a number format dictionary.
U
text string
(Required) A text string specifying a label for displaying the units represented by
this dictionary in a user interface; it is recommended that the label use a universally
recognized abbreviation.
C
number
(Required) The conversion factor used to multiply a value in partial units of the pre-
vious number format array element to obtain a value in the units of this dictionary.
When this entry is in the first number format dictionary in the array, its meaning
(that is, what it is multiplied by) depends on which entry in the rectilinear measure
dictionary (see Table 8.111) references the number format array.
F
name
(Optional; meaningful only for the last dictionary in a number format array) A name
indicating whether and in what manner to display a fractional value from the result
of converting to the units of this dictionary by means of the C entry. Valid values
are:
D Show as decimal to the precision specified by the D entry.
F Show as a fraction with denominator specified by the D entry.
R No fractional part; round to the nearest whole unit.
T No fractional part; truncate to achieve whole units.
Default value: D.
749
SECTION 8.8
Measurement Properties
KEY
TYPE
VALUE
D
integer
(Optional; meaningful only for the last dictionary in a number format array) A posi-
tive integer specifying the precision or denominator of a fractional amount:
• When the value of F is D, this entry represents the precision of a decimal display;
it must be a multiple of 10. Low-order zeros may be truncated unless FD is true.
Default value: 100 (hundredths, corresponding to two decimal digits).
• When the value of F is F, this entry represents the denominator of a fractional dis-
play. The fraction may be reduced unless the value of FD is true. Default value: 16.
FD
boolean
(Optional; meaningful only for the last dictionary in a number format array) If true, a
fractional value formatted according to the D entry may not have its denominator
reduced or low-order zeros truncated.
Default value: false.
RT
text string
(Optional) Text to be used between orders of thousands in display of numerical val-
ues. An empty string indicates that no text is added.
Default value: comma (“,”), the U.S. convention.
RD
text string
(Optional) Text to be used as the decimal point in displaying numerical values. An
empty string indicates that the default should be used.
Default value: period (“.”), the U.S. convention.
PS
text string
(Optional) Text to be concatenated to the left of the label specified by U. An empty
string indicates that no text should be added.
Default value: A single space character (“ ”).
SS
text string
(Optional) Text to be concatenated after the label specified by U. An empty string in-
dicates that no text should be added.
Default value: A single space character (“ ”).
O
name
(Optional) A name indicating the ordering of the label specified by U to the calculat-
ed unit value. Valid values are:
S The label is a suffix to the value.
P The label is a prefix to the value.
Note: The characters specified by PS and SS are concatenated before considering this
entry.
Default value: S.
750
CHAPTER 8
Interactive Features
To use a number format array to create a text string containing the appropriately
formatted units for display in a user interface, apply Algorithm 8.2:
Algorithm 8.2
1.
The entry in the rectilinear measure dictionary (see Table 8.111) that references
the number format array determines the meaning of the initial measurement val-
ue. For example, the X entry specifies user space units, and the T entry specifies
degrees.
2.
Multiply the value specified above by the C entry of the first number format dic-
tionary in the array, which converts the measurement to units of the largest gran-
ularity specified in the array. Apply the value of RT as appropriate.
3.
If the result contains no nonzero fractional portion, concatenate the label speci-
fied by the U entry in the order specified by O, after adding spacing from PS and
SS. The formatting is then complete.
4.
If there is a nonzero fractional portion and no more elements in the array, format
the fractional portion as specified by the RD, F, D, and FD entries of the last dictio-
nary. Concatenate the label specified by the U entry in the order specified by O, af-
ter adding spacing from PS and SS. The formatting is then complete.
5.
If there is a nonzero fractional portion and more elements in the array, proceed to
the next number format dictionary in the array. Multiply its C entry by the frac-
tional result from the previous step. Apply the value of RT as appropriate. Then
proceed to step 3.
Note: The concatenation of elements in this process assumes left-to-right order. Doc-
uments using right-to-left languages can modify the process and the meaning of the
entries as appropriate to produce the correct results.
Example 8.22 shows a measure dictionary that specifies that changes in x or y are
expressed in miles; distances are expressed in miles, feet, and inches; and area is
expressed in acres. Given a sample distance in scaled units of 1.4505 miles, the
formatted text produced by applying the number format array would be
“1 mi 2,378 ft 7 5/8 in”.
751
SECTION 8.9
Document Requirements
Example 8.22
<</Type /Measure
/Subtype /RL
/R (1in = 0.1 mi)
/X [ <</U (mi)
% x offset represented in miles
/C .00139
% Conversion from user space units to miles
/D 100000
]
/D [<< /U (mi) /C 1 >>
% Distance: initial unit is miles; no conversion needed
<< /U (ft) /C 5280 >>
% Conversion from miles to feet
<< /U (in) /C 12
% Conversion from feet to inches
/F /F /D 8 >>
% Fractions of inches rounded to nearest 1/8
]
/A [<</U (acres)
% Area: measured in acres
/C 640 >>
% Conversion from square miles to acres
]
>>
8.9
Document Requirements
Beginning with PDF 1.7, a document can specify requirements that must be
present in a PDF consumer application in order for the document to function
properly. The Requirements entry in the document catalog (see Section 3.6.1,
“Document Catalog”) specifies an array of requirement dictionaries, whose en-
tries are shown in Table 8.113. (See also implementation note 147 in Appendix
H.)
TABLE 8.113 Entries common to all requirement dictionaries
KEY
TYPE
DESCRIPTION
Type
name
(Optional) The type of PDF object that this dictionary describes. If
present, must be Requirement for a requirement dictionary.
S
name
(Required) The type of requirement that this dictionary describes.
Currently, the only defined value is EnableJavaScripts.
RH
array
(Optional) An array of requirement handler dictionaries (see Table
8.114). This array lists the requirement handlers that should be dis-
abled (not executed) if the PDF consumer application can check the
requirement specified in the S entry.
752
CHAPTER 8
Interactive Features
The RH entry ensures backward-capability for this feature. Some PDF documents
include JavaScript segments that verify compliance with certain requirements.
Such JavaScript segments are called requirement handlers. Backward-compatibili-
ty is achieved by ensuring that either the PDF consumer application checks the
requirement or the JavaScript segment checks the requirement, but not both.
When a PDF document is first opened, all JavaScript segments in the document
are executed, including the requirement handlers. If the PDF consumer applica-
tion understands the requirement dictionary, it disables execution of the require-
ment handlers named by the RH entry. If the requirement handler is in JavaScript,
the PDF consumer application looks up the segment using the Names dictionary
(Section 3.6.3, “Name Dictionary).
In PDF 1.7, the only defined requirement type is EnableJavaScripts. This require-
ment indicates that the document requires JavaScript execution to be enabled in
the PDF consumer application. If the EnableJavaScripts requirement is present,
the application can allow the user to choose between keeping JavaScript execu-
tion disabled or temporarily enabling it to benefit from the full function of the
document.
If the EnableJavaScripts requirement is present in a requirement dictionary, the
inclusion of the RH entry that specifies a JavaScript segment would be pointless.
Writing a JavaScript segment to verify that JavaScript is enabled would not
achieve the desired goal. The RH entry is provided to support future capability.
8.9.1
Requirement Handlers
A requirement handler is a program that verifies certain requirements are satis-
fied. Table 8.114 describes the entries in a requirement handler dictionary.
TABLE 8.114 Entries in a requirement handler dictionary
KEY
TYPE
DESCRIPTION
Type
name
(Optional) The type of PDF object that this dictionary describes. If
present, must be ReqHandler for a requirement handler dictionary.
753
SECTION 8.9
Document Requirements
KEY
TYPE
DESCRIPTION
S
name
(Required) The type of requirement handler that this dictionary de-
scribes. Valid requirement handler types are JS (for a JavaScript re-
quirement handlers) and NoOp.
A value of NoOp allows older PDF consumer applications to ignore
unrecognized requirements. This value does not add any specific
entry to the requirement handler dictionary.
Script
text string
(Optional; valid only if the S entry has a value of JS) The name of a
document-level JavaScript action stored in the document name dic-
tionary (see Section 3.6.3, “Name Dictionary). If the PDF consumer
application understands the parent requirement dictionary and can
verify the requirement specified in that dictionary, it disables exe-
cution of the requirement handler identified in this dictionary.
754
CHAPTER 8
Interactive Features
CHAPTER 9
Multimedia Features
9
This chapter describes those features of PDF that support embedding and playing
multimedia content. It contains the following sections:
• Section 9.1, “Multimedia” describes the comprehensive set of multimedia capa-
bilities that were introduced in PDF 1.5.
• Section 9.2, “Sounds,” and Section 9.3, “Movies,” describe features that have
been supported since PDF 1.2.
• Section 9.4, “Alternate Presentations,” describes a slideshow capability that was
introduced in PDF 1.4.
• Section 9.5, “3D Artwork,” describes the capability of embedding three-dimen-
sional graphics in a document, introduced in PDF 1.6.
9.1
Multimedia
PDF 1.5 introduces a comprehensive set of language constructs to enable the fol-
lowing capabilities:
• Arbitrary media types can be embedded in PDF files. (See implementation
note 148 in Appendix H for a list of media types that are recommended for use
with Acrobat 6.0 viewers).
• Embedded media, as well as referenced media outside a PDF file, can be played
with a variety of player software. (In some situations, the player software may
be the viewer application itself.)
Note: The term playing can be used with a wide variety of media, and is not re-
stricted to audio or video. For example, it may be applied to static images such as
JPEGs.
755
756
CHAPTER 9
Multimedia Features
• Media objects may have multiple renditions, which can be chosen at play-time
based on considerations such as available bandwidth.
• Document authors can control play-time requirements, such as which player
software should be used to play a given media object.
• Media objects can be played in various ways; for example, in a floating window
as well as in a region on a page.
• Future extensions to the media constructs can be handled in an appropriate
manner by current viewer applications. Authors can control how old viewers
treat future extensions.
• Document authors can adapt the use of multimedia to accessibility require-
ments.
• On-line media objects can be played efficiently, even when very large.
The following list summarizes the multimedia features and indicates where each
feature is discussed:
• Section 9.1.1, “Viability,” describes the rules for determining when media ob-
jects are suitable for playing on a particular system.
• Rendition actions (see “Rendition Actions” on page 668) are used to begin the
playing of multimedia content.
• A rendition action associates a screen annotation (see “Screen Annotations” on
page 639) with a rendition (see Section 9.1.2, “Renditions”).
• Renditions are of two varieties: media renditions (see “Media Renditions” on
page 762) that define the characteristics of the media to be played, and selector
renditions (see “Selector Renditions” on page 763) that enables choosing which
of a set of media renditions should be played.
• Media renditions contain entries that specify what should be played (see Sec-
tion 9.1.3, “Media Clip Objects”), how it should be played (see Section 9.1.4,
“Media Play Parameters”), and where it should be played (see Section 9.1.5,
“Media Screen Parameters”).
• Section 9.1.6, “Other Multimedia Objects,” describes several PDF objects that
are referenced by the major objects listed above.
Note: Some of the features described in the following sections have references to cor-
responding elements in the Synchronized Multimedia Integration Language (SMIL
2.0) standard (see the Bibliography).
757
SECTION 9.1
Multimedia
9.1.1
Viability
When playing multimedia content, the viewer application must often make deci-
sions such as which player software and which options (for example, volume and
duration) to use. In making these decisions, the viewer must determine the via-
bility of the objects used. If an object is considered non-viable, the media should
not be played. If the object is viable, the media should be played, though possibly
under less than optimum conditions.
There are several entries in the multimedia object dictionaries whose values have
an effect on viability. In particular, some of the object dictionaries define two en-
tries that divide options into one of two categories:
• MH (“must honor”): The options specified by this entry must be honored; other-
wise, the containing object is considered non-viable.
• BE (“best effort”): An attempt should be made to honor the options; however, if
they cannot be honored, the containing object is still considered viable.
MH and BE are both dictionaries, and the same entries are defined for both of
them. In any dictionary where these entries are allowed, both entries may be
present, or only one, or neither. For example, the media play parameters dictio-
nary (see Table 9.14) allows the playback volume to be set by means of the V entry
in its MH and BE dictionaries (see Table 9.15). If the specified volume cannot be
honored, the object is considered non-viable if V is in the MH dictionary, and
playback should not occur. If V is in the BE dictionary (and not also in the MH
dictionary), playback should still occur: the playing software attempts to honor
the specified option as best it can.
Using this mechanism, authors can specify minimum requirements (MH) and
preferred options (BE). They can also specify how entries that are added in the fu-
ture to the multimedia dictionaries are interpreted by old viewer applications. If
an entry that is unrecognized by the viewer is in the MH dictionary, the object is
considered non-viable. If an unrecognized entry is in a BE dictionary, the entry is
ignored and viability is unaffected. Unless otherwise stated, an object should be
considered non-viable if its MH dictionary contains an unrecognized key or an
unrecognized value for a recognized key.
758
CHAPTER 9
Multimedia Features
The following rules apply to the entries in MH and BE dictionaries, which behave
somewhat differently from other PDF dictionaries:
• If an entry is required, the requirement is met if the entry is present in either
the MH dictionary or the BE dictionary.
• If an optional entry is not present in either dictionary, it is considered to be
present with its default value (if one is defined) in the BE dictionary.
• If an instance of the same entry is present in both MH and BE, the instance in
the BE dictionary is ignored unless otherwise specified.
• If the value of an entry in an MH or a BE dictionary is a dictionary or array, it is
treated as an atomic unit when determining viability. That is, all entries within
the dictionary or array must be honored for the containing object to be viable.
Note: When determining whether entries can be honored, it is not required that
each one be evaluated independently, since they may be dependent on one another.
That is, a viewer application or player may examine multiple entries at once (even
within different dictionaries) to determine whether their values can be honored.
The following media objects have MH and BE dictionaries. They function as de-
scribed above, except where noted in the individual sections:
• Rendition (Table 9.2)
• Media clip data (Table 9.11)
• Media clip section (Table 9.13)
• Media play parameters (Table 9.15)
• Media screen parameters (Table 9.18)
9.1.2
Renditions
There are two types of rendition objects:
• A media rendition (see “Media Renditions” on page 762) is a basic media object
that specifies what to play, how to play it, and where to play it.
• A selector rendition (see “Selector Renditions” on page 763) contains an ordered
list of renditions. This list may include other selector renditions, resulting in a
tree whose leaves are media renditions. The viewer application should play the
first viable media rendition it encounters in the tree (see Section 9.1.1, “Viabili-
ty”).
759
SECTION 9.1
Multimedia
Table 9.1 shows the entries common to all rendition dictionaries. The N entry in a
rendition dictionary specifies a name that can be used to access the rendition ob-
ject by means of name tree lookup (see Table 3.28 on page 150). JavaScript actions
(see “JavaScript Actions” on page 709), for example, use this mechanism. Since
the values referenced by name trees must be indirect objects, it is recommended
that all rendition objects be indirect objects.
Note: A rendition dictionary is not required to have a name tree entry. When it
does, the viewer application should ensure that the name specified in the tree is kept
the same as the value of the N entry (for example, if the user interface allows the
name to be changed). It is recommended (but not required) that a document not
contain multiple renditions with the same name.
The MH and BE entries are dictionaries whose entries may be present in one or
the other of them, as described in Section 9.1.1, “Viability”. For renditions, these
dictionaries have a single entry C (see Table 9.2), whose value is a media criteria
dictionary specifying a set of criteria that must be met for the rendition to be con-
sidered viable (see Table 9.3).
The media criteria dictionary behaves somewhat differently than other MH/BE
entries, as they are described in Section 9.1.1. The criteria specified by all of its
entries must be met regardless of whether they are in an MH or a BE dictionary.
The only exception is that if an entry in a BE dictionary is unrecognized by the
viewer application, it does not affect the viability of the object. If a media criteria
dictionary is present in both MH and BE, the entries in both dictionaries are indi-
vidually evaluated, with MH taking precedence (corresponding BE entries are ig-
nored).
TABLE 9.1 Entries common to all rendition dictionaries
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that dictionary describes; if present, must be
Rendition for a rendition object.
S
name
(Required) The type of rendition that this dictionary describes. May be MR for me-
dia rendition or SR for selector rendition. The rendition is considered non-viable if
the viewer application does not recognize the value of this entry.
N
text string
(Optional) A Unicode-encoded text string specifying the name of the rendition for
use in a user interface and for name tree lookup by JavaScript actions.
760
CHAPTER 9
Multimedia Features
KEY
TYPE
VALUE
MH
dictionary
(Optional) A dictionary whose entries (see Table 9.2) must be honored for the ren-
dition to be considered viable.
BE
dictionary
(Optional) A dictionary whose entries (see Table 9.2) need only be honored in a
“best effort” sense.
TABLE 9.2 Entries in a rendition MH/BE dictionary
KEY
TYPE
VALUE
C
dictionary
(Optional) A media criteria dictionary (see Table 9.3).
Note: The media criteria dictionary behaves somewhat differently than other MH/BE
entries described in Section 9.1.1, “Viability.” The criteria specified by all of its entries
must be met regardless of whether it is in an MH or a BE dictionary. The only exception
is that if an entry in a BE dictionary is unrecognized by the viewer application, it does
not affect the viability of the object.
TABLE 9.3 Entries in a media criteria dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
MediaCriteria for a media criteria dictionary.
A
boolean
(Optional) If specified, the value of this entry must match the user’s preference for
whether to hear audio descriptions in order for this object to be viable. Equivalent
to SMIL’s systemAudioDesc attribute.
C
boolean
(Optional) If specified, the value of this entry must match the user’s preference for
whether to see text captions in order for this object to be viable. Equivalent to
SMIL’s systemCaptions attribute.
O
boolean
(Optional) If specified, the value of this entry must match the user’s preference for
whether to hear audio overdubs in order for this object to be viable.
S
boolean
(Optional) If specified, the value of this entry must match the user’s preference for
whether to see subtitles in order for this object to be viable.
R
integer
(Optional) If specified, the system’s bandwidth (in bits per second) must be greater
than or equal to the value of this entry in order for this object to be viable. Equiva-
lent to SMIL’s systemBitrate attribute.
761
SECTION 9.1
Multimedia
KEY
TYPE
VALUE
D
dictionary
(Optional) A dictionary (see Table 9.4) specifying the minimum bit depth required
in order for this object to be viable. Equivalent to SMIL’s systemScreenDepth at-
tribute.
Z
dictionary
(Optional) A dictionary (see Table 9.5) specifying the minimum screen size re-
quired in order for this object to be viable. Equivalent to SMIL’s systemScreenSize at-
tribute.
V
array
(Optional) An array of software identifier objects (see “Software Identifier Dictio-
nary” on page 779). If this entry is present and non-empty, the viewer application
must be identified by one or more of the objects in the array in order for this object
to be viable.
P
array
(Optional) An array containing one or two name objects specifying a minimum and
optionally a maximum PDF language version, in the same format as the Version en-
try in the document catalog (see Table 3.25). If this entry is present and non-empty,
the version of multimedia constructs fully supported by the viewer application must
be within the specified range in order for this object to be viable.
L
array
(Optional) An array of language identifiers (see “Language Identifiers” on page
937). If this entry is present and non-empty, the language in which the viewer appli-
cation is running must exactly match a language identifier, or consist only of a pri-
mary code that matches the primary code of an identifier, in order for this object to
be viable. Equivalent to SMIL’s systemLanguage attribute.
TABLE 9.4 Entries in a minimum bit depth dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
MinBitDepth for a minimum bit depth dictionary.
V
integer
(Required) A positive integer (0 or greater) specifying the minimum screen depth
(in bits) of the monitor for the rendition to be viable. A negative value is not al-
lowed.
M
integer
(Optional) A monitor specifier (see Table 9.28) that specifies which monitor the val-
ue of V should be tested against. If the value is unrecognized, the object is not viable.
Default value: 0.
762
CHAPTER 9
Multimedia Features
TABLE 9.5 Entries in a minimum screen size dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
MinScreenSize for a rendition object.
V
array
(Required) An array containing two non-negative integers. The width and height (in
pixels) of the monitor specified by M must be greater than or equal to the values of
the first and second integers in the array, respectively, in order for this object to be
viable.
M
integer
(Optional) A monitor specifier (see Table 9.28) that specifies which monitor the val-
ue of V should be tested against. If the value is unrecognized, the object is not viable.
Default value: 0.
Media Renditions
Table 9.6 lists the entries in a media rendition dictionary. Its entries specify what
media should be played (C), how (P), and where (SP) it should be played. A media
rendition object is viable if and only if the objects referenced by its C, P, and SP
entries are viable.
C can be omitted only in cases where a referenced player takes no meaningful in-
put. This requires that P is present and that its referenced media play parameters
dictionary (see Table 9.14) contains a PL entry, whose referenced media players
dictionary (see “Media Players Dictionary” on page 777) has a non-empty MU ar-
ray or a non-empty A array.
TABLE 9.6 Additional entries in a media rendition dictionary
KEY
TYPE
VALUE
C
dictionary
(Optional) A media clip dictionary (see Section 9.1.3, “Media Clip Objects”) that
specifies what should be played when the media rendition object is played.
P
dictionary
(Required if C is not present, otherwise optional) A media play parameters dictionary
(see Section 9.1.4, “Media Play Parameters”) that specifies how the media rendition
object should be played.
Default value: a media play parameters dictionary whose entries (see Table 9.14) all
contain their default values.
Большое спасибо!
Ваше мнение очень важно для нас.
Нет комментариевНе стесняйтесь поделиться с нами вашим ценным мнением.
Текст