Content      ..     10      11      12      13     ..

ISO 32000-1 Document management — Portable document format — Part 1: PDF 1.7 - page 12

Table 220 - Entries common to all field dictionaries (continued)

Key

Type

Value

Kids

array

(Sometimes required, as described below) An array of indirect

references to the immediate children of this field.

In a non-terminal field, the Kids array shall refer to field dictionaries

that are immediate descendants of this field. In a terminal field, the

Kids array ordinarily shall refer to one or more separate widget

annotations that are associated with this field. However, if there is only

one associated widget annotation, and its contents have been merged

into the field dictionary, Kids shall be omitted.

T

text string

(Optional) The partial field name (see 12.7.3.2, “Field Names”).

TU

text string

(Optional; PDF 1.3) An alternate field name that shall be used in place

of the actual field name wherever the field shall be identified in the

user interface (such as in error or status messages referring to the

field). This text is also useful when extracting the document’s contents

in support of accessibility to users with disabilities or for other

purposes (see 14.9.3, “Alternate Descriptions”).

TM

text string

(Optional; PDF 1.3) The mapping name that shall be used when

exporting interactive form field data from the document.

Ff

integer

(Optional; inheritable) A set of flags specifying various characteristics

of the field (see Table 221). Default value: 0.

V

(various)

(Optional; inheritable) The field’s value, whose format varies

depending on the field type. See the descriptions of individual field

types for further information.

DV

(various)

(Optional; inheritable) The default value to which the field reverts when

a reset-form action is executed (see 12.7.5.3, “Reset-Form Action”).

The format of this value is the same as that of V.

AA

dictionary

(Optional; PDF 1.2) An additional-actions dictionary defining the field’s

behaviour in response to various trigger events (see 12.6.3, “Trigger

Events”). This entry has exactly the same meaning as the AA entry in

an annotation dictionary (see 12.5.2, “Annotation Dictionaries”).

The value of the field dictionary’s Ff entry is an unsigned 32-bit integer containing flags specifying various

characteristics of the field. Bit positions within the flag word shall be numbered from 1 (low-order) to 32 (high-

order). The flags shown in Table 221 are common to all types of fields. Flags that apply only to specific field

types are discussed in the sub-clauses describing those types. All undefined flag bits shall be reserved and

shall be set to 0.

Table 221 - Field flags common to all field types

Bit position

Name

Meaning

1

ReadOnly

If set, the user may not change the value of the field. Any associated

widget annotations will not interact with the user; that is, they will not

respond to mouse clicks or change their appearance in response to

mouse motions. This flag is useful for fields whose values are

computed or imported from a database.

2

Required

If set, the field shall have a value at the time it is exported by a submit-

form action (see 12.7.5.2, “Submit-Form Action”).

3

NoExport

If set, the field shall not be exported by a submit-form action (see

12.7.5.2, “Submit-Form Action”).

433

12.7.3.2

Field Names

The T entry in the field dictionary (see Table 220) holds a text string defining the field’s partial field name. The

fully qualified field name is not explicitly defined but shall be constructed from the partial field names of the field

and all of its ancestors. For a field with no parent, the partial and fully qualified names are the same. For a field

that is the child of another field, the fully qualified name shall be formed by appending the child field’s partial

name to the parent’s fully qualified name, separated by a PERIOD (2Eh) as shown:

parent’s_full_name . child’s_partial_name

EXAMPLE

If a field with the partial field name PersonalData has a child whose partial name is Address, which in turn

has a child with the partial name ZipCode, the fully qualified name of this last field is

PersonalData . Address . ZipCode

Because the PERIOD is used as a separator for fully qualified names, a partial name shall not contain a

PERIOD character. Thus, all fields descended from a common ancestor share the ancestor’s fully qualified field

name as a common prefix in their own fully qualified names.

It is possible for different field dictionaries to have the same fully qualified field name if they are descendants of

a common ancestor with that name and have no partial field names (T entries) of their own. Such field

dictionaries are different representations of the same underlying field; they should differ only in properties that

specify their visual appearance. In particular, field dictionaries with the same fully qualified field name shall

have the same field type (FT), value (V), and default value (DV).

12.7.3.3

Variable Text

When the contents and properties of a field are known in advance, its visual appearance can be specified by an

appearance stream defined in the PDF file (see 12.5.5, “Appearance Streams,” and 12.5.6.19, “Widget

Annotations”). In some cases, however, the field may contain text whose value is not known until viewing time.

NOTE

Examples include text fields to be filled in with text typed by the user from the keyboard, scrollable list boxes

whose contents are determined interactively at the time the document is displayed and fields containing

current dates or values calculated by a JavaScript.

In such cases, the PDF document cannot provide a statically defined appearance stream for displaying the

field. Instead, the conforming reader shall construct an appearance stream dynamically at viewing time. The

dictionary entries shown in Table 222 provide general information about the field’s appearance that can be

combined with the specific text it contains to construct an appearance stream.

Table 222 - Additional entries common to all fields containing variable text

Key

Type

Value

DA

string

(Required; inheritable) The default appearance string containing a sequence of

valid page-content graphics or text state operators that define such properties

as the field’s text size and colour.

Q

integer

(Optional; inheritable) A code specifying the form of quadding (justification) that

shall be used in displaying the text:

0

Left-justified

1

Centered

2

Right-justified

Default value: 0 (left-justified).

DS

text string

(Optional; PDF 1.5) A default style string, as described in 12.7.3.4, “Rich Text

Strings.”

434

Table 222 - Additional entries common to all fields containing variable text (continued)

Key

Type

Value

RV

text string

(Optional; PDF 1.5) A rich text string, as described in 12.7.3.4, “Rich Text

or text

Strings.”

stream

The new appearance stream becomes the normal appearance (N) in the appearance dictionary associated

with the field’s widget annotation (see Table 168). (If the widget annotation has no appearance dictionary, the

conforming reader shall create one and store it in the annotation dictionary’s AP entry.)

In PDF 1.5, form fields that have the RichText flag set (see Table 226) specify formatting information as

described in 12.7.3.4, “Rich Text Strings.” For these fields, the following conventions are not used, and the

entire annotation appearance shall be regenerated each time the value is changed.

For non-rich text fields, the appearance stream—which, like all appearance streams, is a form XObject—has

the contents of its form dictionary initialized as follows:

•

The resource dictionary

(Resources) shall be created using resources from the interactive form

dictionary’s DR entry (see Table 218).

•

The lower-left corner of the bounding box (BBox) is set to coordinates (0, 0) in the form coordinate system.

The box’s top and right coordinates are taken from the dimensions of the annotation rectangle (the Rect

entry in the widget annotation dictionary).

•

All other entries in the appearance stream’s form dictionary are set to their default values (see 8.10, “Form

XObjects”).

EXAMPLE

The appearance stream includes the following section of marked content, which represents the portion of

the stream that draws the text:

/Tx BMC

% Begin marked content with tag Tx

q

% Save graphics state

… Any required graphics state changes, such as clipping…

BT

% Begin text object

… Default appearance string ( DA )…

… Text-positioning and text-showing operators to show the variable text…

ET

% End text object

Q

% Restore graphics state

EMC

% End marked content

The BMC (begin marked content) and EMC (end marked content) operators are discussed in 14.6,

“Marked Content.” q (save graphics state) and Q (restore graphics state) are discussed in 8.4.4,

“Graphics State Operators.” BT (begin text object) and ET (end text object) are discussed in 9.4, “Text

Objects.” See Example 1 in 12.7.8, “XFA Forms” for an example.

The default appearance string (DA) contains any graphics state or text state operators needed to establish the

graphics state parameters, such as text size and colour, for displaying the field’s variable text. Only operators

that are allowed within text objects shall occur in this string (see Figure 9). At a minimum, the string shall

include a Tf (text font) operator along with its two operands, font and size. The specified font value shall match

a resource name in the Font entry of the default resource dictionary (referenced from the DR entry of the

interactive form dictionary; see Table 218). A zero value for size means that the font shall be auto-sized: its size

shall be computed as a function of the height of the annotation rectangle.

The default appearance string shall contain at most one Tm (text matrix) operator. If this operator is present,

the conforming reader shall replace the horizontal and vertical translation components with positioning values it

determines to be appropriate, based on the field value, the quadding (Q) attribute, and any layout rules it

employs. If the default appearance string contains no Tm operator, the viewer shall insert one in the

appearance stream

(with appropriate horizontal and vertical translation components) after the default

appearance string and before the text-positioning and text-showing operators for the variable text.

435

To update an existing appearance stream to reflect a new field value, the conforming reader shall first copy any

needed resources from the document’s DR dictionary (see Table 218) into the stream’s Resources dictionary.

(If the DR and Resources dictionaries contain resources with the same name, the one already in the

Resources dictionary shall be left intact, not replaced with the corresponding value from the DR dictionary.)

The conforming reader shall then replace the existing contents of the appearance stream from /Tx BMC to the

matching EMC with the corresponding new contents as shown in Example 1 in "Check Boxes," 12.7.4, “Field

Types.” (If the existing appearance stream contains no marked content with tag Tx, the new contents shall be

appended to the end of the original stream.)

12.7.3.4

Rich Text Strings

Beginning with PDF 1.5, the text contents of variable text form fields, as well as markup annotations, may

include formatting (style) information. These rich text strings are fully-formed XML documents that conform to

the rich text conventions specified for the XML Forms Architecture (XFA) specification, which is itself a subset

of the XHTML 1.0 specification, augmented with a restricted set of CSS2 style attributes (see the Bibliography

for references to all these standards).

Table 223 lists the XHTML elements that may appear in rich text strings. The <body> element is the root

element; its required attributes are listed in Table 224. Other elements (<p> and <span>) contain enclosed text

that may take style attributes, which are listed in Table 225. These style attributes are CSS inline style property

declarations of the form name:value, with each declaration separated by a SEMICOLON (3Bh), as illustrated in

the Example in "Radio Buttons," 12.7.4, “Field Types.”

In PDF 1.6, PDF supports the rich text elements and attributes specified in the XML Forms Architecture (XFA)

Specification, 2.2 (see Bibliography). These rich text elements and attributes are a superset of those described

in Table 223, Table 224 and Table 225. In PDF 1.7, PDF supports the rich text elements and attributes specified

in the XML Forms Architecture (XFA) Specification, 2.4 (see Bibliography).

Table 223 - XHTML elements used in rich text strings

element

Description

<body>

The element at the root of the XML document. Table 224 lists the required attributes for

this element.

<p>

Encloses text that shall be interpreted as a paragraph. It may take the style attributes

listed in Table 225.

<i>

Encloses text that shall be displayed in an italic font.

<b>

Encloses text that shall be displayed in a bold font.

<span>

Groups text solely for the purpose of applying styles (using the attributes in Table 225).

Table 224 - Attributes of the <body> element

Attribute

Description

xmlns

The default namespaces for elements within the rich text string. Shall be

xmlns="http://www.w3.org/1999/xhtml"

xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0".

xfa:contentType

Shall be "text/html".

436

Table 224 - Attributes of the <body> element (continued)

Attribute

Description

xfa:APIVersion

A string that identifies the software used to generate the rich text string. It shall be of

the form software_name:software_version, where

software_name identifies the software by name. It shall not contain spaces.

software_version identifies the version of the software. It consists of a series of

integers separated by decimal points. Each integer is a version number, the leftmost

value being a major version number, with values to the right increasingly minor.

When comparing strings, the versions shall be compared in order.

NOTE

“5.2” is less than “5.13” because 2 is less than 13; the string is not

treated as a decimal number. When comparing strings with different

numbers of sections, the string with fewer sections is implicitly padded

on the right with sections containing

“0” to make the number of

sections equivalent.

xfa:spec

The version of the XML Forms Architecture (XFA) specification to which the rich text

string complies. If the file being written conforms to PDF 1.5, then the rich text string

shall conform to XFA 2.0, and this attribute shall be XFA 2.0; if the file being written

conforms to PDF 1.6, then the rich text string shall conform to XFA 2.2, and this

attribute shall be XFA 2.2; and if the file being written conforms to PDF 1.7, then the

rich text string shall conform to XFA 2.4, and this attribute shall be XFA 2.4.

Table 225 - CSS2 style attributes used in rich text strings

Attribute

Value

Description

text-align

keyword

Horizontal alignment. Possible values: left, right, and center.

vertical-align

decimal

An amount by which to adjust the baseline of the enclosed text. A

positive value indicates a superscript; a negative value indicates a

subscript. The value is of the form <decimal number>pt, optionally

preceded by a sign, and followed by “pt”.

EXAMPLE

-3pt, 4pt.

font-size

decimal

The font size of the enclosed text. The value is of the form

<decimal number>pt.

font-style

keyword

Specifies the font style of the enclosed text. Possible values: normal,

italic.

font-weight

keyword

The weight of the font for the enclosed text. Possible values: normal,

bold, 100, 200, 300, 400, 500, 600, 700, 800, 900.

normal is equivalent to 400, and bold is equivalent to 700.

font-family

list

A font name or list of font names that shall be used to display the

enclosed text. (If a list is provided, the first one containing glyphs for

the specified text shall be used.)

font

list

A shorthand CSS font property of the form

font:<font-style> <font-weight> <font-size> <font-family>

color

RGB

The colour of the enclosed text. It can be in one of two forms:

value

#rrggbb with a 2-digit hexadecimal value for each component

rgb(rrr,ggg,bbb) with a decimal value for each component.

Although the values specified by the color property are interpreted as

sRGB values, they shall be transformed into values in a non-ICC

based colour space when used to generate the annotation’s

appearance.

437

Table 225 - CSS2 style attributes used in rich text strings (continued)

Attribute

Value

Description

text-decoration

keyword

One of the following keywords:

underline: The enclosed text shall be underlined.

line-through: The enclosed text shall have a line drawn through it.

font-stretch

keyword

Specifies a normal, condensed or extended face from a font family.

Supported values from narrowest to widest are ultra-condensed,

extra-condensed, condensed, semi-condensed, normal, semi-

expanded, expanded, extra-expanded, and ultra-expanded.

Rich text strings shall be specified by the RV entry of variable text form field dictionaries (see Table 222) and

the RC entry of markup annotation dictionaries (see Table 170). Rich text strings may be packaged as text

streams (see 7.9.3, “Text Streams”). Form fields using rich text streams should also have the RichText flag set

(see Table 228).

A default style string shall be specified by the DS entry for free text annotations (see Table 174) or variable text

form fields (see Table 222). This string specifies the default values for style attributes, which shall be used for

any style attributes that are not explicitly specified for the annotation or field. All attributes listed in Table 225

are legal in the default style string. This string, in addition to the RV or RC entry, shall be used to generate the

appearance.

NOTE 1

Markup annotations other than free text annotations (see 12.5.6.2, “Markup Annotations”) do not use a default

style string because their appearances are implemented using platform controls requiring the conforming

reader to pick an appropriate system font for display.

When a form field or annotation contains rich text strings, the flat text (character data) of the string should also

be preserved (in the V entry for form fields and the Contents entry for annotations). This enables older readers

to read and edit the data (although with loss of formatting information). The DA entry should be written out as

well when the file is saved.

When a rich text string specifies font attributes, the conforming reader shall use font name selection as

described in Section 15.3 of the CSS2 specification (see the Bibliography). Precedence should be given to the

fonts in the default resources dictionary, as specified by the DR entry in Table 218.

EXAMPLE

The following example illustrates the entries in a widget annotation dictionary for rich text. The DS entry

specifies the default font. The RV entry contains two paragraphs of rich text: the first paragraph specifies

bold and italic text in the default font; the second paragraph changes the font size.

/DS (font: 18pt Arial)

% Default style string using an abbreviated font

% descriptor to specify 18pt text using an Arial font

/RV (<?xml version="1.0"?><body xmlns="http://www.w3.org/1999/xtml"

xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/"

xfa:contentType="text/html" xfa:APIVersion="Acrobat:8.0.0" xfa:spec="2.4">

<p style="text-align:left">

<b>

<i>

Here is some bold italic text

</i>

</b>

</p>

<p style= "font-size:16pt">

This text uses default text state parameters but changes the font size to 16.

</p>

</body> )

438

12.7.4

Field Types

12.7.4.1

General

Interactive forms support the following field types:

•

Button fields represent interactive controls on the screen that the user can manipulate with the mouse.

They include pushbuttons, check boxes, and radio buttons.

•

Text fields are boxes or spaces in which the user can enter text from the keyboard.

•

Choice fields contain several text items, at most one of which may be selected as the field value. They

include scrollable list boxes and combo boxes.

•

Signature fields represent digital signatures and optional data for authenticating the name of the signer and

the document’s contents.

The following sub-clauses describe each of these field types in detail. Further types may be added in the future.

12.7.4.2

Button Fields

12.7.4.2.1

General

A button field (field type Btn) represents an interactive control on the screen that the user can manipulate with

the mouse. There are three types of button fields:

•

A pushbutton is a purely interactive control that responds immediately to user input without retaining a

permanent value (see 12.7.4.2.2, “Pushbuttons”).

•

A check box toggles between two states, on and off (see 12.7.4.2.3, “Check Boxes”).

•

Radio button fields contain a set of related buttons that can each be on or off. Typically, at most one radio

button in a set may be on at any given time, and selecting any one of the buttons automatically deselects

all the others. (There are exceptions to this rule, as noted in "Radio Buttons.")

For button fields, bits 15, 16, 17, and 26 shall indicate the intended behaviour of the button field. A conforming

reader shall follow the intended behaviour, as defined in Table 226 and clauses 12.7.4.2.2, "Pushbuttons",

12.7.4.2.3, "Check Boxes" and 12.7.4.2.4, "Radio Buttons".

Table 226 - Field flags specific to button fields

Bit position

Name

Meaning

15

NoToggleToOff

(Radio buttons only) If set, exactly one radio button shall be

selected at all times; selecting the currently selected button has no

effect. If clear, clicking the selected button deselects it, leaving no

button selected.

16

Radio

If set, the field is a set of radio buttons; if clear, the field is a check

box. This flag may be set only if the Pushbutton flag is clear.

17

Pushbutton

If set, the field is a pushbutton that does not retain a permanent

value.

26

RadiosInUnison

(PDF 1.5) If set, a group of radio buttons within a radio button field

that use the same value for the on state will turn on and off in

unison; that is if one is checked, they are all checked. If clear, the

buttons are mutually exclusive (the same behavior as HTML radio

buttons).

439

Beginning with PDF 1.4, the field dictionary for check boxes and radio buttons may contain an optional Opt

entry (see Table 227). If present, the Opt entry shall be an array of text strings representing the export value of

each annotation in the field. It may be used for the following purposes:

•

To represent the export values of check box and radio button fields in non-Latin writing systems. Because

name objects in the appearance dictionary are limited to PDFDocEncoding, they cannot represent non-

Latin text.

•

To allow radio buttons or check boxes to be checked independently, even if they have the same export

value.

EXAMPLE 2

A group of check boxes may be duplicated on more than one page such that the desired behavior is that

when a user checks a box, the corresponding boxes on each of the other pages are also checked. In this

case, each of the corresponding check boxes is a widget in the Kids array of a check box field.

NOTE

For radio buttons, the same behavior shall occur only if the RadiosInUnison flag is set. If it is not set, at most

one radio button in a field shall be set at a time.

Table 227 - Additional entry specific to check box and radio button fields

Key

Type

Value

Opt

array of text

(Optional; inheritable; PDF 1.4) An array containing one entry for each widget

strings

annotation in the Kids array of the radio button or check box field. Each entry

shall be a text string representing the on state of the corresponding widget

annotation.

When this entry is present, the names used to represent the on state in the AP

dictionary of each annotation (for example, /1, /2) numerical position (starting with

0) of the annotation in the Kids array, encoded as a name object. This allows

distinguishing between the annotations even if two or more of them have the

same value in the Opt array.

12.7.4.2.4

Radio Buttons

A radio button field is a set of related buttons. Like check boxes, individual radio buttons have two states, on

and off. A single radio button may not be turned off directly but only as a result of another button being turned

on. Typically, a set of radio buttons (annotations that are children of a single radio button field) have at most one

button in the on state at any given time; selecting any of the buttons automatically deselects all the others.

NOTE

An exception occurs when multiple radio buttons in a field have the same on state and the RadiosInUnison flag

is set. In that case, turning on one of the buttons turns on all of them.

The field type is Btn, the Pushbutton flag (see Table 226) is clear, and the Radio flag is set. This type of button

field has an additional flag, NoToggleToOff, which specifies, if set, that exactly one of the radio buttons shall be

selected at all times. In this case, clicking the currently selected button has no effect; if the NoToggleToOff flag

is clear, clicking the selected button deselects it, leaving no button selected.

The Kids entry in the radio button field’s field dictionary (see Table 220) holds an array of widget annotations

representing the individual buttons in the set. The parent field’s V entry holds a name object corresponding to

the appearance state of whichever child field is currently in the on state; the default value for this entry is Off.

EXAMPLE

This example shows the object definitions for a set of radio buttons.

10 0 obj

% Radio button field

<< /FT /Btn

/Ff

…

% … Radio flag = 1, Pushbutton = 0…

/T ( Credit card )

/V /cardbrand1

/Kids

[

11 0 R

12 0 R

]

441

flag in the field dictionary’s Ff entry. Table 228 shows the flags pertaining to this type of field. A text field shall

have a field type of Tx. A conforming PDF file, and a conforming processor shall obey the usage guidelines in

Table 228.

Table 228 - Field flags specific to text fields

Bit position

Name

Meaning

13

Multiline

If set, the field may contain multiple lines of text; if clear, the field’s

text shall be restricted to a single line.

14

Password

If set, the field is intended for entering a secure password that

should not be echoed visibly to the screen. Characters typed from

the keyboard shall instead be echoed in some unreadable form,

such as asterisks or bullet characters.

NOTE

To protect password confidentiality, readers should

never store the value of the text field in the PDF file if

this flag is set.

21

FileSelect

(PDF 1.4) If set, the text entered in the field represents the

pathname of a file whose contents shall be submitted as the value

of the field.

23

DoNotSpellCheck

(PDF 1.4) If set, text entered in the field shall not be spell-checked.

24

DoNotScroll

(PDF 1.4) If set, the field shall not scroll (horizontally for single-line

fields, vertically for multiple-line fields) to accommodate more text

than fits within its annotation rectangle. Once the field is full, no

further text shall be accepted for interactive form filling; for non-

interactive form filling, the filler should take care not to add more

character than will visibly fit in the defined area.

25

Comb

(PDF 1.5) May be set only if the MaxLen entry is present in the text

field dictionary (see Table 229) and if the Multiline, Password, and

FileSelect flags are clear. If set, the field shall be automatically

divided into as many equally spaced positions, or combs, as the

value of MaxLen, and the text is laid out into those combs.

26

RichText

(PDF 1.5) If set, the value of this field shall be a rich text string (see

12.7.3.4, “Rich Text Strings”). If the field has a value, the RV entry

of the field dictionary (Table 222) shall specify the rich text string.

The field’s text shall be held in a text string (or, beginning with PDF 1.5, a stream) in the V (value) entry of the

field dictionary. The contents of this text string or stream shall be used to construct an appearance stream for

displaying the field, as described under 12.7.3.3, “Variable Text.” The text shall be presented in a single style

(font, size, colour, and so forth), as specified by the DA (default appearance) string.

If the FileSelect flag (PDF 1.4) is set, the field shall function as a file-select control. In this case, the field’s text

represents the pathname of a file whose contents shall be submitted as the field’s value:

•

For fields submitted in HTML Form format, the submission shall use the MIME content type multipart / form-

data, as described in Internet RFC 2045, Multipurpose Internet Mail Extensions (MIME), Part One: Format

of Internet Message Bodies (see the Bibliography).

•

For Forms Data Format (FDF) submission, the value of the V entry in the FDF field dictionary (see FDF

Fields in 12.7.7.3, “FDF Catalog”) shall be a file specification (7.11, “File Specifications”) identifying the

selected file.

•

XML format is not supported for file-select controls; therefore, no value shall be submitted in this case.

Besides the usual entries common to all fields (see Table 220) and to fields containing variable text (see

Table 222), the field dictionary for a text field may contain the additional entry shown in Table 229.

443

Table 229 - Additional entry specific to a text field

Key

Type

Value

MaxLen

integer

(Optional; inheritable) The maximum length of the field’s text, in characters.

EXAMPLE

The following example shows the object definitions for a typical text field.

6 0 obj

<< /FT /Tx

/Ff

…

% Set Multiline flag

/T ( Silly prose )

/DA ( 0 0 1 rg /Ti 12 Tf )

/V ( The quick brown fox ate the lazy mouse )

/AP << /N 5 0 R >>

>>

endobj

5 0 obj

<< /Resources 21 0 R

/Length 172

>>

stream

/Tx BMC

q

BT

0 0 1 rg

/Ti

12 Tf

1 0 0 1 100 100 Tm

0 0 Td

( The quick brown fox ) Tj

0 -13 Td

( ate the lazy mouse. ) Tj

ET

Q

EMC

endstream

endobj

12.7.4.4

Choice Fields

A choice field shall have a field type of Ch that contains several text items, one or more of which shall be

selected as the field value. The items may be presented to the user in one of the following two forms:

•

A scrollable list box

•

A combo box consisting of a drop-down list. The combo box may be accompanied by an editable text box

in which the user can type a value other than the predefined choices, as directed by the value of the Edit bit

in the Ff entry.

Table 230 - Field flags specific to choice fields

Bit position

Name

Meaning

18

Combo

If set, the field is a combo box; if clear, the field is a list box.

19

Edit

If set, the combo box shall include an editable text box as well

as a drop-down list; if clear, it shall include only a drop-down

list. This flag shall be used only if the Combo flag is set.

444

Table 230 - Field flags specific to choice fields (continued)

Bit position

Name

Meaning

20

Sort

If set, the field’s option items shall be sorted alphabetically. This

flag is intended for use by writers, not by readers. Conforming

readers shall display the options in the order in which they

occur in the Opt array (see Table 231).

22

MultiSelect

(PDF 1.4) If set, more than one of the field’s option items may

be selected simultaneously; if clear, at most one item shall be

selected.

23

DoNotSpellCheck

(PDF 1.4) If set, text entered in the field shall not be spell-

checked. This flag shall not be used unless the Combo and Edit

flags are both set.

27

CommitOnSelChange

(PDF 1.5) If set, the new value shall be committed as soon as a

selection is made (commonly with the pointing device). In this

case, supplying a value for a field involves three actions:

selecting the field for fill-in, selecting a choice for the fill-in

value, and leaving that field, which finalizes or “commits” the

data choice and triggers any actions associated with the entry

or changing of this data. If this flag is on, then processing does

not wait for leaving the field action to occur, but immediately

proceeds to the third step.

This option enables applications to perform an action once a

selection is made, without requiring the user to exit the field. If

clear, the new value is not committed until the user exits the

field.

The various types of choice fields are distinguished by flags in the Ff entry, as shown in Table 230. Table 231

shows the field dictionary entries specific to choice fields.

Table 231 - Additional entries specific to a choice field

Key

Type

Value

Opt

array

(Optional) An array of options that shall be presented to the user. Each element

of the array is either a text string representing one of the available options or an

array consisting of two text strings: the option’s export value and the text that

shall be displayed as the name of the option.

If this entry is not present, no choices should be presented to the user.

TI

integer

(Optional) For scrollable list boxes, the top index (the index in the Opt array of the

first option visible in the list). Default value: 0.

I

array

(Sometimes required, otherwise optional; PDF 1.4) For choice fields that allow

multiple selection (MultiSelect flag set), an array of integers, sorted in ascending

order, representing the zero-based indices in the Opt array of the currently

selected option items. This entry shall be used when two or more elements in the

Opt array have different names but the same export value or when the value of

the choice field is an array. This entry should not be used for choice fields that do

not allow multiple selection. If the items identified by this entry differ from those in

the V entry of the field dictionary (see discussion following this Table), the V entry

shall be used.

The Opt array specifies the list of options in the choice field, each of which shall be represented by a text string

that shall be displayed on the screen. Each element of the Opt array contains either this text string by itself or a

two-element array, whose second element is the text string and whose first element is a text string representing

the export value that shall be used when exporting interactive form field data from the document.

The field dictionary’s V (value) entry (see Table 220) identifies the item or items currently selected in the choice

field. If the field does not allow multiple selection—that is, if the MultiSelect flag (PDF 1.4) is not set—or if

445

multiple selection is supported but only one item is currently selected, V is a text string representing the name

of the selected item, as given in the field dictionary’s Opt array. If multiple items are selected, V is an array of

such strings. (For items represented in the Opt array by a two-element array, the name string is the second of

the two array elements.) The default value of V is null, indicating that no item is currently selected.

EXAMPLE

The following example shows a typical choice field definition.

<< /FT /Ch

/Ff

…

/T ( Body Color )

/V ( Blue )

/Opt

[

( Red )

( My favorite color )

( Blue )

]

>>

12.7.4.5

Signature Fields

A signature field (PDF 1.3) is a form field that contains a digital signature (see 12.8, “Digital Signatures”). The

field dictionary representing a signature field may contain the additional entries listed in Table 232, as well as

the standard entries described in Table 220. The field type (FT) shall be Sig, and the field value (V), if present,

shall be a signature dictionary containing the signature and specifying various attributes of the signature field

(see Table 252).

NOTE 1

This signature form field serves two primary purposes. The first is to define the form field that will provide the

visual signing properties for display but it also may hold information needed later when the actual signing takes

place, such as the signature technology to use. This carries information from the author of the document to the

software that later does the signing.

NOTE 2

Filling in (signing) the signature field entails updating at least the V entry and usually also the AP entry of the

associated widget annotation. Exporting a signature field typically exports the T, V, and AP entries.

Like any other field, a signature field may be described by a widget annotation dictionary containing entries

pertaining to an annotation as well as a field (see 12.5.6.19, “Widget Annotations”). The annotation rectangle

(Rect) in such a dictionary shall give the position of the field on its page. Signature fields that are not intended

to be visible shall have an annotation rectangle that has zero height and width. Conforming readers shall treat

such signatures as not visible. Conforming readers shall also treat signatures as not visible if either the Hidden

bit or the NoView bit of the F entry is true. The F entry is described in Table 164, and annotation flags are

described in Table 165.

The appearance dictionary (AP) of a signature field’s widget annotation defines the field’s visual appearance on

the page (see 12.5.5, “Appearance Streams”).

Table 232 - Additional entries specific to a signature field

Key

Type

Value

Lock

dictionary

(Optional; shall be an indirect reference; PDF 1.5) A signature field lock

dictionary that specifies a set of form fields that shall be locked when this

signature field is signed. Table 233 lists the entries in this dictionary.

SV

dictionary

(Optional; shall be an indirect reference; PDF 1.5) A seed value dictionary (see

Table 234) containing information that constrains the properties of a signature

that is applied to this field.

The signature field lock dictionary (described in Table 233) contains field names from the signature seed value

dictionary (described in Table 234) that cannot be changed through the user interface of a conforming reader.

446

Table 233 - Entries in a signature field lock dictionary

Key

Type

Value

Type

name

(Optional) The type of PDF object that this dictionary describes; if present,

shall be SigFieldLock for a signature field lock dictionary.

Action

name

(Required) A name which, in conjunction with Fields, indicates the set of fields

that should be locked. The value shall be one of the following:

All

All fields in the document

Include

All fields specified in Fields

Exclude

All fields except those specified in Fields

Fields

array

(Required if the value of Action is Include or Exclude) An array of text strings

containing field names.

The value of the SV entry in the field dictionary is a seed value dictionary whose entries (see Table 234)

provide constraining information that shall be used at the time the signature is applied. Its Ff entry specifies

whether the other entries in the dictionary shall be honoured or whether they are merely recommendations.

The seed value dictionary may include seed values for private entries belonging to multiple handlers. A given

handler shall use only those entries that are pertinent to itself and ignore the others.

Table 234 - Entries in a signature field seed value dictionary

Key

Type

Value

Type

name

(Optional) The type of PDF object that this dictionary describes; if

present, shall be SV for a seed value dictionary.

Ff

integer

(Optional) A set of bit flags specifying the interpretation of specific

entries in this dictionary. A value of 1 for the flag indicates that the

associated entry is a required constraint. A value of 0 indicates that the

associated entry is an optional constraint. Bit positions are 1 (Filter); 2

(SubFilter); 3 (V); 4 (Reasons); 5 (LegalAttestation); 6 (AddRevInfo);

and 7 (DigestMethod). Default value: 0.

Filter

name

(Optional) The signature handler that shall be used to sign the signature

field. Beginning with PDF 1.7, if Filter is specified and the Ff entry

indicates this entry is a required constraint, then the signature handler

specified by this entry shall be used when signing; otherwise, signing

shall not take place. If Ff indicates that this is an optional constraint, this

handler may be used if it is available. If it is not available, a different

handler may be used instead.

SubFilter

array

(Optional) An array of names indicating encodings to use when signing.

The first name in the array that matches an encoding supported by the

signature handler shall be the encoding that is actually used for signing.

If SubFilter is specified and the Ff entry indicates that this entry is a

required constraint, then the first matching encodings shall be used

when signing; otherwise, signing shall not take place. If Ff indicates that

this is an optional constraint, then the first matching encoding shall be

used if it is available. If none is available, a different encoding may be

used.

DigestMethod

array

(Optional; PDF 1.7) An array of names indicating acceptable digest

algorithms to use while signing. The value shall be one of SHA1,

SHA256, SHA384, SHA512 and RIPEMD160. The default value is

implementation-specific.

This property is only applicable if the digital credential signing contains

RSA public/private keys. If it contains DSA public/ private keys, the

digest algorithm is always SHA1 and this attribute shall be ignored.

447

Table 234 - Entries in a signature field seed value dictionary (continued)

Key

Type

Value

V

real

(Optional) The minimum required capability of the signature field seed

value dictionary parser. A value of 1 specifies that the parser shall be

able to recognize all seed value dictionary entries in a PDF 1.5 file. A

value of 2 specifies that it shall be able to recognize all seed value

dictionary entries specified.

The Ff entry indicates whether this shall be treated as a required

constraint.

Cert

dictionary

(Optional) A certificate seed value dictionary (see Table 235) containing

information about the characteristics of the certificate that shall be used

when signing.

Reasons

array

(Optional) An array of text strings that specifying possible reasons for

signing a document. If specified, the reasons supplied in this entry

replace those used by conforming products.

If the Reasons array is provided and the Ff entry indicates that

Reasons is a required constraint, one of the reasons in the array shall

be used for the signature dictionary; otherwise, signing shall not take

place. If the Ff entry indicates Reasons is an optional constraint, one of

the reasons in the array may be chosen or a custom reason can be

provided.

If the Reasons array is omitted or contains a single entry with the value

PERIOD (2Eh) and the Ff entry indicates that Reasons is a required

constraint, the Reason entry shall be omitted from the signature

dictionary (see Table 252).

MDP

dictionary

(Optional; PDF 1.6) A dictionary containing a single entry whose key is

P and whose value is an integer between 0 and 3. A value of 0 defines

the signature as an author signature (see 12.8, “Digital Signatures”).

The values 1 through 3 shall be used for certification signatures and

correspond to the value of P in a DocMDP transform parameters

dictionary (see Table 254).

If this MDP key is not present or the MDP dictionary does not contain a

P entry, no rules shall be defined regarding the type of signature or its

permissions.

TimeStamp

dictionary

(Optional; PDF 1.6) A time stamp dictionary containing two entries:

URL An ASCII string specifying the URL of a time-stamping server,

providing a time stamp that is compliant with RFC 3161, Internet

X.509 Public Key Infrastructure Time-Stamp Protocol (see the

Bibliography).

Ff

An integer whose value is 1 (the signature shall have a time

stamp) or 0 (the signature need not have a time stamp). Default

value: 0.

NOTE

Please see 12.8.3.3, "PKCS#7 Signatures as used in ISO

32000" for more details about hashing.

LegalAttestation

array

(Optional; PDF 1.6) An array of text strings specifying possible legal

attestations (see 12.8.5, “Legal Content Attestations”). The value of the

corresponding flag in the Ff entry indicates whether this is a required

constraint.

448

Table 234 - Entries in a signature field seed value dictionary (continued)

Key

Type

Value

AddRevInfo

boolean

(Optional; PDF 1.7) A flag indicating whether revocation checking shall

be carried out. If AddRevInfo is true, the conforming processor shall

perform the following additional tasks when signing the signature field:

Perform revocation checking of the certificate (and the corresponding

issuing certificates) used to sign.

Include the revocation information within the signature value.

Three SubFilter values have been defined for ISO 32000. For those

values the AddRevInfo value shall be true only if SubFilter is

adbe.pkcs7.detached or adbe.pkcs7.sha1. If SubFilter is

x509.rsa_sha1, this entry shall be omitted or set to false. Additional

SubFilters may be defined that also use AddRevInfo values.

If AddRevInfo is true and the Ff entry indicates this is a required

constraint, then the preceding tasks shall be performed. If they cannot

be performed, then signing shall fail.

Default value: false

NOTE 1

Revocation information is carried in the signature data as

specified by PCKS#7. See 12.8.3.3, "PKCS#7 Signatures

as used in ISO 32000".

NOTE 2

The trust anchors used are determined by the signature

handlers for both creation and validation.

For optional keys that are not present, no constraint shall be placed upon the signature handler for that

property when signing.

Table 235 - Entries in a certificate seed value dictionary

Key

Type

Value

Type

name

(Optional) The type of PDF object that this dictionary describes; if

present, shall be SVCert for a certificate seed value dictionary.

Ff

integer

(Optional) A set of bit flags specifying the interpretation of specific

entries in this dictionary. A value of 1 for the flag means that a signer

shall be required to use only the specified values for the entry. A value

of

0 means that other values are permissible. Bit positions are 1

(Subject);

2

(Issuer);

3

(OID);

4

(SubjectDN);

5 (Reserved);

6

(KeyUsage); 7 (URL).

Default value: 0.

Subject

array

(Optional) An array of byte strings containing DER-encoded X.509v3

certificates that are acceptable for signing. X.509v3 certificates are

described in RFC

3280, Internet X.509 Public Key Infrastructure,

Certificate and Certificate Revocation List

(CRL) Profile

(see the

Bibliography). The value of the corresponding flag in the Ff entry

indicates whether this is a required constraint.

449

Table 235 - Entries in a certificate seed value dictionary (continued)

Key

Type

Value

SubjectDN

array of

(Optional; PDF 1.7) An array of dictionaries, each specifying a Subject

dictionaries

Distinguished Name (DN) that shall be present within the certificate for it

to be acceptable for signing. The certificate ultimately used for the

digital signature shall contain all the attributes specified in each of the

dictionaries in this array.

(PDF keys and values are mapped to

certificate attributes and values.) The certificate is not constrained to

use only attribute entries from these dictionaries but may contain

additional attributes.The Subject Distinguished Name is described in

RFC 3280 (see the Bibliography). The key can be any legal attribute

identifier (OID). Attribute names shall contain characters in the set a-z

A-Z 0-9 and PERIOD.

Certificate attribute names are used as key names in the dictionaries in

this array. Values of the attributes are used as values of the keys.

Values shall be text strings.

The value of the corresponding flag in the Ff entry indicates whether

this entry is a required constraint.

KeyUsage

array of

(Optional; PDF 1.7) An array of ASCII strings, where each string

ASCII

specifies an acceptable key-usage extension that shall be present in the

strings

signing certificate. Multiple strings specify a range of acceptable key-

usage extensions. The key-usage extension is described in RFC 3280.

Each character in a string represents a key-usage type, where the order

of the characters indicates the key-usage extension it represents. The

first through ninth characters in the string, from left to right, represent

the required value for the following key-usage extensions:

1 digitalSignature

4

dataEncipherment

7 cRLSign

2 non-Repudiation

5

keyAgreement

8 encipherOnly

3 keyEncipherment

6

keyCertSign

9 decipherOnly

Any additional characters shall be ignored. Any missing characters or

characters that are not one of the following values, shall be treated as

‘X’. The following character values shall be supported:

0

Corresponding key-usage shall not be set.

1

Corresponding key-usage shall be set.

X State of the corresponding key-usage does not matter.

EXAMPLE 1

The string values ‘1’ and ‘1XXXXXXXX’ represent

settings where the key-usage type digitalSignature is

set and the state of all other key-usage types do not

matter.

The value of the corresponding flag in the Ff entry indicates whether

this is a required constraint.

Issuer

array

(Optional) An array of byte strings containing DER-encoded X.509v3

certificates of acceptable issuers. If the signer’s certificate refers to any

of the specified issuers (either directly or indirectly), the certificate shall

be considered acceptable for signing. The value of the corresponding

flag in the Ff entry indicates whether this is a required constraint.

This array may contain self-signed certificates.

OID

array

(Optional) An array of byte strings that contain Object Identifiers (OIDs)

of the certificate policies that shall be present in the signing certificate.

EXAMPLE 2

An example of such a string is:

(2.16.840.1.113733.1.7.1.1).

This field shall only be used if the value of Issuer is not empty. The

certificate policies extension is described in RFC

3280

(see the

Bibliography). The value of the corresponding flag in the Ff entry

indicates whether this is a required constraint.

450

Table 235 - Entries in a certificate seed value dictionary (continued)

Key

Type

Value

URL

ASCII string

(Optional) A URL, the use for which shall be defined by the URLType

entry.

URLType

Name

(Optional; PDF 1.7) A name indicating the usage of the URL entry.

There are standard uses and there can be implementation-specific uses

for this URL. The following value specifies a valid standard usage:

Browser - The URL references content that shall be displayed in a web

browser to allow enrolling for a new credential if a matching credential is

not found. The Ff attribute’s URL bit shall be ignored for this usage.

Third parties may extend the use of this attribute with their own attribute

values, which shall conform to the guidelines described in Annex E.

The default value is Browser.

12.7.5

Form Actions

12.7.5.1

General

Interactive forms also support special types of actions in addition to those described in 12.6.4, “Action Types”:

•

submit-form action

•

reset-form action

•

import-data action

12.7.5.2

Submit-Form Action

Upon invocation of a submit-form action, a conforming processor shall transmit the names and values of

selected interactive form fields to a specified uniform resource locator (URL),

NOTE Presumably, the URL is the address of a Web server that will process them and send back a

response.

The value of the action dictionary’s Flags entry shall be an non-negative integer containing flags specifying

various characteristics of the action. Bit positions within the flag word shall be numbered starting with 1

(low-order). Table 237 shows the meanings of the flags; all undefined flag bits shall be reserved and shall be

set to 0.

Table 236 - Additional entries specific to a submit-form action

Key

Type

Value

S

name

(Required) The type of action that this dictionary describes;

shall be SubmitForm for a submit-form action.

F

file specification

(Required) A URL file specification

(see

7.11.5,

“URL

Specifications”) giving the uniform resource locator (URL) of

the script at the Web server that will process the submission.

451

Table 236 - Additional entries specific to a submit-form action (continued)

Key

Type

Value

Fields

array

(Optional) An array identifying which fields to include in the

submission or which to exclude, depending on the setting of

the Include/Exclude flag in the Flags entry (see Table 237).

Each element of the array shall be either an indirect

reference to a field dictionary or

(PDF 1.3) a text string

representing the fully qualified name of a field. Elements of

both kinds may be mixed in the same array.

If this entry is omitted, the Include/Exclude flag shall be

ignored, and all fields in the document’s interactive form shall

be submitted except those whose NoExport flag

(see

Table 221) is set. Fields with no values may also be

excluded, as dictated by the value of the

IncludeNoValueFields flag; see Table 237.

Flags

integer

(Optional; inheritable) A set of flags specifying various

characteristics of the action (see Table 237). Default value: 0.

Table 237 - Flags for submit-form actions

Bit position

Name

Meaning

1

Include/Exclude

If clear, the Fields array

(see Table 236) specifies which

fields to include in the submission. (All descendants of the

specified fields in the field hierarchy shall be submitted as

well.)

If set, the Fields array tells which fields to exclude. All fields

in the document’s interactive form shall be submitted except

those listed in the Fields array and those whose NoExport

flag (see Table 221) is set and fields with no values if the

IncludeNoValueFields flag is clear.

2

IncludeNoValueFields

If set, all fields designated by the Fields array and the

Include/Exclude flag shall be submitted, regardless of

whether they have a value (V entry in the field dictionary). For

fields without a value, only the field name shall be

transmitted.

If clear, fields without a value shall not be submitted.

3

ExportFormat

Meaningful only if the SubmitPDF and XFDF flags are clear. If

set, field names and values shall be submitted in HTML Form

format. If clear, they shall be submitted in Forms Data Format

(FDF); see 12.7.7, “Forms Data Format.”

4

GetMethod

If set, field names and values shall be submitted using an

HTTP GET request. If clear, they shall be submitted using a

POST request. This flag is meaningful only when the

ExportFormat flag is set; if ExportFormat is clear, this flag

shall also be clear.

452

Table 237 - Flags for submit-form actions (continued)

Bit position

Name

Meaning

5

SubmitCoordinates

If set, the coordinates of the mouse click that caused the

submit-form action shall be transmitted as part of the form

data. The coordinate values are relative to the upper-left

corner of the field’s widget annotation rectangle. They shall

be represented in the data in the format

name . x = xval & name . y = yval

where name is the field’s mapping name (TM in the field

dictionary) if present; otherwise, name is the field name. If the

value of the TM entry is a single ASCII SPACE

(20h)

character, both the name and the ASCII PERIOD (2Eh)

following it shall be suppressed, resulting in the format

x = xval & y = yval

This flag shall be used only when the ExportFormat flag is

set. If ExportFormat is clear, this flag shall also be clear.

6

XFDF

(PDF 1.4) shall be used only if the SubmitPDF flags are clear.

If set, field names and values shall be submitted as XFDF.

7

IncludeAppendSaves

(PDF 1.4) shall be used only when the form is being

submitted in Forms Data Format (that is, when both the

XFDF and ExportFormat flags are clear). If set, the submitted

FDF file shall include the contents of all incremental updates

to the underlying PDF document, as contained in the

Differences entry in the FDF dictionary (see Table 243). If

clear, the incremental updates shall not be included.

8

IncludeAnnotations

(PDF 1.4) shall be used only when the form is being

submitted in Forms Data Format (that is, when both the

XFDF and ExportFormat flags are clear). If set, the submitted

FDF file shall include includes all markup annotations in the

underlying PDF document

(see

12.5.6.2,

“Markup

Annotations”). If clear, markup annotations shall not be

included.

9

SubmitPDF

(PDF 1.4) If set, the document shall be submitted as PDF,

using the MIME content type application / pdf (described in

Internet RFC 2045, Multipurpose Internet Mail Extensions

(MIME), Part One: Format of Internet Message Bodies; see

the Bibliography). If set, all other flags shall be ignored except

GetMethod.

10

CanonicalFormat

(PDF 1.4) If set, any submitted field values representing

dates shall be converted to the standard format described in

7.9.4, “Dates.”

NOTE 1

The interpretation of a form field as a date is not

specified explicitly in the field itself but only in

the JavaScript code that processes it.

453

Table 237 - Flags for submit-form actions (continued)

Bit position

Name

Meaning

11

ExclNonUserAnnots

(PDF 1.4) shall be used only when the form is being

submitted in Forms Data Format (that is, when both the

XFDF and ExportFormat flags are clear) and the

IncludeAnnotations flag is set. If set, it shall include only

those markup annotations whose T entry (see Table 170)

matches the name of the current user, as determined by the

remote server to which the form is being submitted.

NOTE 2

The T entry for markup annotations specifies the

text label that is displayed in the title bar of the

annotation’s pop-up window and is assumed to

represent the name of the user authoring the

annotation.

NOTE 3

This allows multiple users to collaborate in

annotating a single remote PDF document

without affecting one another’s annotations.

12

ExclFKey

(PDF 1.4) shall be used only when the form is being

submitted in Forms Data Format (that is, when both the

XFDF and ExportFormat flags are clear). If set, the submitted

FDF shall exclude the F entry.

14

EmbedForm

(PDF 1.5) shall be used only when the form is being

submitted in Forms Data Format (that is, when both the

XFDF and ExportFormat flags are clear). If set, the F entry of

the submitted FDF shall be a file specification containing an

embedded file stream representing the PDF file from which

the FDF is being submitted.

The set of fields whose names and values are to be submitted shall be defined by the Fields array in the action

dictionary (Table 236) together with the Include/Exclude and IncludeNoValueFields flags in the Flags entry

(Table 237). Each element of the Fields array shall identify an interactive form field, either by an indirect

reference to its field dictionary or (PDF 1.3) by its fully qualified field name (see 12.7.3.2, “Field Names”). If the

Include/Exclude flag is clear, the submission consists of all fields listed in the Fields array, along with any

descendants of those fields in the field hierarchy. If the Include/Exclude flag is set, the submission shall consist

of all fields in the document’s interactive form except those listed in the Fields array.

The NoExport flag in the field dictionary’s Ff entry (see Table 220 and Table 221) takes precedence over the

action’s Fields array and Include/Exclude flag. Fields whose NoExport flag is set shall not be included in a

submit-form action.

Field names and values may be submitted in any of the following formats, depending on the settings of the

action’s ExportFormat, SubmitPDF, and XFDF flags (see the Bibliography for references):

•

HTML Form format (described in the HTML 4.01 Specification)

•

Forms Data Format (FDF), which is described in 12.7.7, “Forms Data Format.”

•

XFDF, a version of FDF based on XML. XFDF is described in the Adobe technical note XML Forms Data

Format Specification, Version 2.0. XML is described in the W3C document Extensible Markup Language

(XML) 1.1)

•

PDF (in this case, the entire document shall be submitted rather than individual fields and values).

The name submitted for each field shall be its fully qualified name (see 12.7.3.2, “Field Names”), and the value

shall be specified by the V entry in its field dictionary.

454

For pushbutton fields submitted in FDF, the value submitted shall be that of the AP entry in the field’s widget

annotation dictionary. If the submit-form action dictionary contains no Fields entry, such pushbutton fields shall

not be submitted.

Fields with no value (that is, whose field dictionary does not contain a V entry) are ordinarily not included in the

submission. The submit-form action’s IncludeNoValueFields flag may override this behaviour. If this flag is set,

such valueless fields shall be included in the submission by name only, with no associated value.

12.7.5.3

Reset-Form Action

Upon invocation of a reset-form action, a conforming processor shall reset selected interactive form fields to

their default values; that is, it shall set the value of the V entry in the field dictionary to that of the DV entry (see

Table 220). If no default value is defined for a field, its V entry shall be removed. For fields that can have no

value (such as pushbuttons), the action has no effect. Table 238 shows the action dictionary entries specific to

this type of action.

The value of the action dictionary’s Flags entry is a non-negative containing flags specifying various

characteristics of the action. Bit positions within the flag word shall be numbered starting from 1 (low-order).

Only one flag is defined for this type of action. All undefined flag bits shall be reserved and shall be set to 0.

Table 238 - Additional entries specific to a reset-form action

Key

Type

Value

S

name

(Required) The type of action that this dictionary describes; shall

be ResetForm for a reset-form action.

Fields

array

(Optional) An array identifying which fields to reset or which to

exclude from resetting, depending on the setting of the Include/

Exclude flag in the Flags entry (see Table 239). Each element of

the array shall be either an indirect reference to a field dictionary

or (PDF 1.3) a text string representing the fully qualified name of a

field. Elements of both kinds may be mixed in the same array.

If this entry is omitted, the Include/Exclude flag shall be ignored;

all fields in the document’s interactive form are reset.

Flags

integer

(Optional; inheritable) A set of flags specifying various

characteristics of the action (see Table 239). Default value: 0.

Table 239 - Flag for reset-form actions

Bit position

Name

Meaning

1

Include/Exclude

If clear, the Fields array (see Table 238) specifies which fields to

reset. (All descendants of the specified fields in the field hierarchy

are reset as well.) If set, the Fields array indicates which fields to

exclude from resetting; that is, all fields in the document’s

interactive form shall be reset except those listed in the Fields

array.

455

12.7.5.4

Import-Data Action

Upon invocation of an import-data action, a conforming processor shall import Forms Data Format (FDF) data

into the document’s interactive form from a specified file.

Table 240 - Additional entries specific to an import-data action

Key

Type

Value

S

name

(Required) The type of action that this dictionary describes; shall be

ImportData for an import-data action.

F

file specification

(Required) The FDF file from which to import the data.

12.7.6

Named Pages

The optional Pages entry (PDF 1.3) in a document’s name dictionary (see 7.7.4, “Name Dictionary”) contains a

name tree that maps name strings to individual pages within the document. Naming a page allows it to be

referenced in two different ways:

•

An import-data action can add the named page to the document into which FDF is being imported, either

as a page or as a button appearance.

•

A script executed by a JavaScript action can add the named page to the current document as a regular

page.

A named page that is intended to be visible to a user shall be left in the page tree (see 7.7.3, “Page Tree”), and

there shall be a reference to it in the appropriate leaf node of the name dictionary’s Pages tree. If the page is

not intended to be displayed by the reader, it shall be referenced from the name dictionary’s Templates tree

instead. Such invisible pages shall have an object type of Template rather than Page and shall have no Parent

or B entry (see Table 30).

12.7.7

Forms Data Format

12.7.7.1

General

This sub-clause describes Forms Data Format (FDF), the file format used for interactive form data (PDF 1.2).

FDF can be used when submitting form data to a server, receiving the response, and incorporating it into the

interactive form. It can also be used to export form data to stand-alone files that can be stored, transmitted

electronically, and imported back into the corresponding PDF interactive form. In addition, beginning in PDF

1.3, FDF can be used to define a container for annotations that are separate from the PDF document to which

they apply.

FDF is based on PDF; it uses the same syntax and has essentially the same file structure (7.5, “File Structure”).

However, it differs from PDF in the following ways:

•

The cross-reference table (7.5.4, “Cross-Reference Table”) is optional.

•

FDF files shall not be updated (see 7.5.6, “Incremental Updates”). Objects shall only be of generation 0,

and no two objects within an FDF file shall have the same object number.

•

The document structure is much simpler than PDF, since the body of an FDF document consists of only

one required object.

•

The length of a stream shall not be specified by an indirect object.

FDF uses the MIME content type application / vnd . fdf. On the Windows and UNIX platforms, FDF files have the

extension . fdf; on Mac OS, they have file type ' FDF '.

456

12.7.7.2

FDF File Structure

12.7.7.2.1

General

An FDF file shall be structured in essentially the same way as a PDF file but contains only those elements

required for the export and import of interactive form and annotation data. It consists of three required elements

and one optional element (see Figure 65):

•

A one-line header identifying the version number of the PDF specification to which the file conforms

•

A body containing the objects that make up the content of the file

•

An optional cross-reference table containing information about the indirect objects in the file

•

An optional trailer giving the location of the cross-reference table and of certain special objects within the

body of the file

Header

Body

Cross-reference

table (optional)

Trailer

Figure 65 - FDF file structure

12.7.7.2.2

FDF Header

The first line of an FDF file shall be a header, which shall contain

%FDF-1 . 2

The version number is given by the Version entry in the FDF catalogue dictionary (see 12.7.7.3, “FDF

Catalog”).

12.7.7.2.3

FDF Body

The body of an FDF file shall consist of a sequence of indirect objects representing the file’s catalogue (see

12.7.7.3, “FDF Catalog”) and any additional objects that the catalogue references. The objects are of the same

basic types described in 7.5, “File Structure” (other than the %PDF-n.m and %%EOF comments described in

7.5, “File Structure”) have no semantics. They are not necessarily preserved by applications that edit PDF

files.” Just as in PDF, objects in FDF can be direct or indirect.

457

12.7.7.2.4

FDF Trailer

The trailer of an FDF file enables a reader to find significant objects quickly within the body of the file. The last

line of the file contains only the end-of-file marker, %%EOF. This marker shall be preceded by the FDF trailer

dictionary, consisting of the keyword trailer followed by a series of one or more key-value pairs enclosed in

double angle brackets (<<… >>) (using LESS-THAN SIGNs (3Ch) and GREATER-THAN SIGNs (3Eh)). The

only required key is Root, whose value is an indirect reference to the file’s catalogue dictionary

(see

Table 242). The trailer may optionally contain additional entries for objects that are referenced from within the

catalogue.

Table 241 - Entry in the FDF trailer dictionary

Key

Type

Value

Root

dictionary

(Required; shall be an indirect reference) The Catalog object for this FDF file

(see 12.7.7.3, “FDF Catalog”).

Thus, the trailer has the overall structure

trailer

<< /Root c 0 R

key₂ value₂

…

key_n value_n

>>

%%EOF

where c is the object number of the file’s catalogue dictionary.

12.7.7.3

FDF Catalog

12.7.7.3.1

General

The root node of an FDF file’s object hierarchy is the Catalog dictionary, located by means of the Root entry in

the file’s trailer dictionary (see FDF Trailer in 12.7.7.2, “FDF File Structure”). As shown in Table 241, the only

required entry in the catalogue is FDF; its value shall be an FDF dictionary (Table 243), which in turn shall

contain references to other objects describing the file’s contents. The catalogue may also contain an optional

Version entry identifying the version of the PDF specification to which this FDF file conforms.

Table 242 - Entries in the FDF catalog dictionary

Key

Type

Value

Version

name

(Optional; PDF 1.4) The version of the FDF specification to

which this FDF file conforms (for example, 1.4) if later than

the version specified in the file’s header (see FDF Header in

12.7.7.2, “FDF File Structure”). If the header specifies a later

version, or if this entry is absent, the document conforms to

the version specified in the header.

The value of this entry is a name object, not a number, and

therefore shall be preceded by a slash character (/) when

written in the FDF file (for example, /1.4).

FDF

dictionary

(Required) The FDF dictionary for this file (see Table 243).

458

Table 243 - Entries in the FDF dictionary

Key

Type

Value

F

file specification

(Optional) The source file or target file: the PDF document file

that this FDF file was exported from or is intended to be

imported into.

ID

array

(Optional) An array of two byte strings constituting a file

identifier (see 14.4, “File Identifiers”) for the source or target

file designated by F, taken from the ID entry in the file’s trailer

dictionary (see 7.5.5, “File Trailer”).

Fields

array

(Optional) An array of FDF field dictionaries (see FDF Fields

in 12.7.7.3, “FDF Catalog”) describing the root fields (those

with no ancestors in the field hierarchy) that shall be exported

or imported. This entry and the Pages entry shall not both be

present.

Status

PDFDocEncoded

(Optional) A status string that shall be displayed indicating

string

the result of an action, typically a submit-form action (see

12.7.5.2, “Submit-Form Action”). The string shall be encoded

with PDFDocEncoding. This entry and the Pages entry shall

not both be present.

Pages

array

(Optional; PDF 1.3) An array of FDF page dictionaries (see

FDF Pages in 12.7.7.3, “FDF Catalog”) describing pages that

shall be added to a PDF target document. The Fields and

Status entries shall not be present together with this entry.

Encoding

name

(Optional; PDF 1.3) The encoding that shall be used for any

FDF field value or option (V or Opt in the field dictionary; see

Table 246) or field name that is a string and does not begin

with the Unicode prefix U+FEFF.

Default value: PDFDocEncoding.

Other allowed values include Shift_JIS, BigFive, GBK,

UHC, utf_8, utf_16

Annots

array

(Optional; PDF 1.3) An array of FDF annotation dictionaries

(see FDF Annotation Dictionaries in 12.7.7.3, “FDF Catalog”).

The array may include annotations of any of the standard

types listed in Table 169 except Link, Movie, Widget,

PrinterMark, Screen, and TrapNet.

459

Table 243 - Entries in the FDF dictionary (continued)

Key

Type

Value

Differences

stream

(Optional; PDF 1.4) A stream containing all the bytes in all

incremental updates made to the underlying PDF document

since it was opened (see 7.5.6, “Incremental Updates”). If a

submit-form action submitting the document to a remote

server as FDF has its IncludeAppendSaves flag set (see

12.7.5.2, “Submit-Form Action”), the contents of this stream

shall be included in the submission. This allows any digital

signatures (see 12.8, “Digital Signatures”) to be transmitted

to the server. An incremental update shall be automatically

performed just before the submission takes place, in order to

capture all changes made to the document.

The submission shall include the full set of incremental

updates back to the time the document was first opened,

even if some of them may already have been included in

intervening submissions.

Although a Fields or Annots entry (or both) may be present

along with Differences, there is no requirement that their

contents will be consistent with each other. In particular, if

Differences contains a digital signature, only the values of

the form fields given in the Differences stream shall be

considered trustworthy under that signature.

Target

string

(Optional; PDF 1.4) The name of a browser frame in which

the underlying PDF document shall be opened. This mimics

the behaviour of the target attribute in HTML < href > tags.

EmbeddedFDFs

array

(Optional; PDF 1.4) An array of file specifications (see 7.11,

“File Specifications”) representing other FDF files embedded

within this one (7.11.4, “Embedded File Streams”).

JavaScript

dictionary

(Optional; PDF 1.4) A JavaScript dictionary (see Table 245)

defining document-level JavaScript scripts.

Embedded FDF files specified in the FDF dictionary’s EmbeddedFDFs entry may be encrypted. Besides the

usual entries for an embedded file stream, the stream dictionary representing such an encrypted FDF file shall

contain the additional entry shown in Table 244 to identify the revision number of the FDF encryption algorithm

used to encrypt the file. Although the FDF encryption mechanism is separate from the one for PDF file

encryption described in 7.6, “Encryption,” revision 1 (the only one defined) uses a similar RC4 encryption

algorithm based on a 40-bit encryption key. The key shall be computed by means of an MD5 hash, using a

padded user-supplied password as input. The computation shall be identical to steps (a) and (b) of the

"Algorithm 2: Computing an encryption key" in 7.6.3.3, "Encryption Key Algorithm"; the first 5 bytes of the result

shall be the encryption key for the embedded FDF file.

Table 244 - Additional entry in an embedded file stream dictionary for an encrypted FDF file

Key

Type

Value

EncryptionRevision

integer

(Required if the FDF file is encrypted; PDF 1.4) The revision number of

the FDF encryption algorithm used to encrypt the file. This value shall

be defined at the time of publication is 1.

The JavaScript entry in the FDF dictionary holds a JavaScript dictionary containing JavaScript scripts that

shall be defined globally at the document level, rather than associated with individual fields. The dictionary may

contain scripts defining JavaScript functions for use by other scripts in the document, as well as scripts that

shall be executed immediately before and after the FDF file is imported. Table 245 shows the contents of this

dictionary.

460

Table 245 - Entries in the JavaScript dictionary

Key

Type

Value

Before

text string or

(Optional) A text string or text stream containing a JavaScript script

text stream

that shall be executed just before the FDF file is imported.

After

text string or

(Optional) A text string or text stream containing a JavaScript script

text stream

that shall be executed just after the FDF file is imported.

AfterPermsReady

text string or

(Optional; PDF

1.6) A text string or text stream containing a

text stream

JavaScript script that shall be executed after the FDF file is

imported and the usage rights in the PDF document have been

determined (see 12.8.2.3, “UR”).

Verification of usage rights requires the entire file to be present, in

which case execution of this script shall be deferred until that

requirement is met.

Doc

array

(Optional) An array defining additional JavaScript scripts that shall

be added to those defined in the JavaScript entry of the

document’s name dictionary (see 7.7.4, “Name Dictionary”). The

array shall contain an even number of elements, organized in pairs.

The first element of each pair shall be a name and the second shall

be a text string or text stream defining the script corresponding to

that name. Each of the defined scripts shall be added to those

already defined in the name dictionary and shall then be executed

before the script defined in the Before entry is executed.

NOTE

As described in 12.6.4.16, “JavaScript Actions,” these

scripts are used to define JavaScript functions for use

by other scripts in the document.

12.7.7.3.2

FDF Fields

Each field in an FDF file shall be described by an FDF field dictionary. Table 246 shows the contents of this type

of dictionary. Most of the entries have the same form and meaning as the corresponding entries in a field

dictionary (Table 220, Table 222, Table 229, and Table 231) or a widget annotation dictionary (Table 168 and

Table 188). Unless otherwise indicated in the table, importing a field causes the values of the entries in the FDF

field dictionary to replace those of the corresponding entries in the field with the same fully qualified name in the

target document.

Table 246 - Entries in an FDF field dictionary

Key

Type

Value

Kids

array

(Optional) An array containing the immediate children of this field.

Unlike the children of fields in a PDF file, which shall be specified as indirect

object references, those of an FDF field may be either direct or indirect objects.

T

text string

(Required) The partial field name (see 12.7.3.2, “Field Names”).

V

(various)

(Optional) The field’s value, whose format varies depending on the field type;

see the descriptions of individual field types in 12.7.4, “Field Types” for further

information.

Ff

integer

(Optional) A set of flags specifying various characteristics of the field (see

Table 221, Table 226, Table 228, and Table 230). When imported into an

interactive form, the value of this entry shall replace that of the Ff entry in the

form’s corresponding field dictionary. If this field is present, the SetFf and ClrFf

entries, if any, shall be ignored.

SetFf

integer

(Optional) A set of flags to be set (turned on) in the Ff entry of the form’s

corresponding field dictionary. Bits equal to

1 in SetFf shall cause the

corresponding bits in Ff to be set to 1. This entry shall be ignored if an Ff entry

is present in the FDF field dictionary.

461

Table 246 - Entries in an FDF field dictionary (continued)

Key

Type

Value

ClrFf

integer

(Optional) A set of flags to be cleared (turned off) in the Ff entry of the form’s

corresponding field dictionary. Bits equal to

1 in ClrFf shall cause the

corresponding bits in Ff to be set to 0. If a SetFf entry is also present in the

FDF field dictionary, it shall be applied before this entry. This entry shall be

ignored if an Ff entry is present in the FDF field dictionary.

F

integer

(Optional) A set of flags specifying various characteristics of the field’s widget

annotation (see 12.5.3, “Annotation Flags”). When imported into an interactive

form, the value of this entry shall replace that of the F entry in the form’s

corresponding annotation dictionary. If this field is present, the SetF and ClrF

entries, if any, shall be ignored.

SetF

integer

(Optional) A set of flags to be set (turned on) in the F entry of the form’s

corresponding widget annotation dictionary. Bits equal to 1 in SetF shall cause

the corresponding bits in F to be set to 1. This entry shall be ignored if an F

entry is present in the FDF field dictionary.

ClrF

integer

(Optional) A set of flags to be cleared (turned off) in the F entry of the form’s

corresponding widget annotation dictionary. Bits equal to 1 in ClrF shall cause

the corresponding bits in F to be set to 0. If a SetF entry is also present in the

FDF field dictionary, it shall be applied before this entry. This entry shall be

ignored if an F entry is present in the FDF field dictionary.

AP

dictionary

(Optional) An appearance dictionary specifying the appearance of a

pushbutton field

(see Pushbuttons in

12.7.4.2,

“Button Fields”). The

appearance dictionary’s contents are as shown in Table 168, except that the

values of the N, R, and D entries shall all be streams.

APRef

dictionary

(Optional; PDF 1.3) A dictionary holding references to external PDF files

containing the pages to use for the appearances of a pushbutton field. This

dictionary is similar to an appearance dictionary (see Table 168), except that

the values of the N, R, and D entries shall all be named page reference

dictionaries (Table 250). This entry shall be ignored if an AP entry is present.

IF

dictionary

(Optional; PDF 1.3; button fields only) An icon fit dictionary (see Table 247)

specifying how to display a button field’s icon within the annotation rectangle of

its widget annotation.

Opt

array

(Required; choice fields only) An array of options that shall be presented to the

user. Each element of the array shall take one of two forms:

A text string representing one of the available options

A two-element array consisting of a text string representing one of the available

options and a default appearance string for constructing the item’s appearance

dynamically at viewing time (see 12.7.3.3, “Variable Text”).

A

dictionary

(Optional) An action that shall be performed when this field’s widget annotation

is activated (see 12.6, “Actions”).

AA

dictionary

(Optional) An additional-actions dictionary defining the field’s behaviour in

response to various trigger events (see 12.6.3, “Trigger Events”).

RV

text string or

(Optional; PDF 1.5) A rich text string, as described in 12.7.3.4, “Rich Text

text stream

Strings.”

462

In an FDF field dictionary representing a button field, the optional IF entry holds an icon fit dictionary (PDF 1.3)

specifying how to display the button’s icon within the annotation rectangle of its widget annotation. Table 247

shows the contents of this type of dictionary.

Table 247 - Entries in an icon fit dictionary

Key

Type

Value

SW

name

(Optional) The circumstances under which the icon shall be scaled inside the

annotation rectangle:

A

Always scale.

B

Scale only when the icon is bigger than the annotation rectangle.

S

Scale only when the icon is smaller than the annotation rectangle.

N

Never scale.

Default value: A.

S

name

(Optional) The type of scaling that shall be used:

A Anamorphic scaling: Scale the icon to fill the annotation rectangle exactly,

without regard to its original aspect ratio (ratio of width to height).

P Proportional scaling: Scale the icon to fit the width or height of the annotation

rectangle while maintaining the icon’s original aspect ratio. If the required

horizontal and vertical scaling factors are different, use the smaller of the two,

centering the icon within the annotation rectangle in the other dimension.

Default value: P.

A

array

(Optional) An array of two numbers that shall be between 0.0 and 1.0 indicating

the fraction of leftover space to allocate at the left and bottom of the icon. A value

of [ 0.0

0.0 ] shall position the icon at the bottom-left corner of the annotation

rectangle. A value of [ 0.5 0.5 ] shall center it within the rectangle. This entry shall

be used only if the icon is scaled proportionally. Default value: [ 0.5 0.5 ].

FB

boolean

(Optional; PDF 1.5) If true, indicates that the button appearance shall be scaled

to fit fully within the bounds of the annotation without taking into consideration the

line width of the border. Default value: false.

12.7.7.3.3

FDF Pages

The optional Pages field in an FDF dictionary (see Table 243) shall contain an array of FDF page dictionaries

(PDF 1.3) describing new pages that shall be added to the target document. Table 248 shows the contents of

this type of dictionary.

Table 248 - Entries in an FDF page dictionary

Key

Type

Value

Templates

array

(Required) An array of FDF template dictionaries (see Table 249) that

shall describe the named pages that serve as templates on the page.

Info

dictionary

(Optional) An FDF page information dictionary that shall contain

additional information about the page.

An FDF template dictionary shall contain information describing a named page that serves as a template.

Table 249 shows the contents of this type of dictionary.

463

Table 249 - Entries in an FDF template dictionary

Key

Type

Value

TRef

dictionary

(Required) A named page reference dictionary (see Table 250) that shall

specify the location of the template.

Fields

array

(Optional) An array of references to FDF field dictionaries (see Table 246)

describing the root fields that shall be imported (those with no ancestors

in the field hierarchy).

Rename

boolean

(Optional) A flag that shall specify whether fields imported from the

template shall be renamed in the event of name conflicts with existing

fields; see the Note in this sub-clause for further discussion. Default

value: true.

NOTE

The names of fields imported from a template can sometimes conflict with those of existing fields in the target

document. This can occur, for example, if the same template page is imported more than once or if two

different templates have fields with the same names.

The Rename flag does not define a renaming algorithm (see Annex J).

The TRef entry in an FDF template dictionary shall hold a named page reference dictionary that shall describe

the location of external templates or page elements. Table 250 shows the contents of this type of dictionary.

Table 250 - Entries in an FDF named page reference dictionary

Key

Type

Value

Name

string

(Required) The name of the referenced page.

F

file specification

(Optional) The file containing the named page. If this entry is absent, it

shall be assumed that the page resides in the associated PDF file.

12.7.7.3.4

FDF Annotation Dictionaries

Each annotation dictionary in an FDF file shall have a Page entry (see Table 251) that shall indicate the page of

the source document to which the annotation is attached.

Table 251 - Additional entry for annotation dictionaries in an FDF file

Key

Type

Value

Page

integer

(Required for annotations in FDF files) The ordinal page number on

which this annotation shall appear, where page 0 is the first page.

12.7.8

XFA Forms

PDF 1.5 introduces support for interactive forms based on the Adobe XML Forms Architecture (XFA). The XFA

entry in the interactive forms dictionary (see Table 218) specifies an XFA resource, which shall be an XML

stream that contains the form information. The format of an XFA resource is described in the XML Data

Package (XDP) Specification (see the Bibliography).

The XFA entry shall be either a stream containing the entire XFA resource or an array specifying individual

packets that together make up the XFA resource. The resource includes but is not limited to the following

information:

•

The form template (specified in the template packet), which describes the characteristics of the form,

including its fields, calculations, validations, and formatting. The XML Template Specification describes the

architecture of a form template (see Bibliography).

464

•

Additionally, modification detection may be specified by a signature reference dictionary. The

TransformMethod entry shall specify the general method for modification detection, and the

TransformParams entry shall specify the variable portions of the method.

A PDF document may contain the following standard types of signatures:

•

One or more approval signatures. These signatures appear in signature form fields (see 12.7.4.5,

“Signature Fields”). The signature dictionary corresponding to each signature shall be the value of the form

field (as specified by its V entry). The signature dictionary shall contain a ByteRange entry representing a

byte range digest, as described previously. A signature shall be validated by recomputing the digest and

comparing it with the one stored in the signature.

NOTE 1

If a signed document is modified and saved by incremental update (see 7.5.6, “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 certification signature (PDF 1.5). The signature dictionary of a certification signature shall be

the value of a signature field and shall contain a ByteRange entry. It may also be referenced from the

DocMDP entry in the permissions dictionary (see 12.8.4, “Permissions”). The signature dictionary shall

contain a signature reference dictionary (see Table 253) that has a DocMDP transform method. See

12.8.2.2, “DocMDP” for information on how these signatures shall be created and validated.

A signature dictionary for a certification or approval signature may also have a signature reference

dictionary with a FieldMDP transform method; see 12.8.2.4, “FieldMDP.”

•

At most two usage rights signatures (PDF 1.5). Its signature dictionary shall be referenced from the UR3

(PDF 1.6) entry in the permissions dictionary, whose entries are listed in Table 258, (not from a signature

field). The signature dictionary shall contain a Reference entry whose value is a signature reference

dictionary that has a UR transform method. See 12.8.2.3, “UR” for information on how these signatures

shall be created and validated.

Table 252 - Entries in a signature dictionary

Key

Type

Value

Type

name

(Optional) The type of PDF object that this dictionary describes; if

present, shall 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 shall be also the name of the signature handler that was

used to create the signature. If Prop_Build is present, it may be used

to determine the name of the handler that created the signature (which

is typically the same as Filter but is not needed to be). A conforming

reader may substitute a different handler when verifying the signature,

as long as it supports the specified SubFilter format. Example

signature handlers are Adobe.PPKLite, Entrust.PPKEF, CICI.SignIt,

and VeriSign.PPKVS. The name of the filter (i.e. signature handler)

shall be identified in accordance with the rules defined in Annex E.

SubFilter

name

(Optional) A name that describes the encoding of the signature value

and key information in the signature dictionary. A conforming reader

may use any handler that supports this format to validate the

signature.

(PDF 1.6) The following values for public-key cryptographic signatures

shall be used: adbe.x509.rsa_sha1, adbe.pkcs7.detached, and

adbe.pkcs7.sha1

(see

12.8.3,

“Signature Interoperability”). Other

values may be defined by developers, and when used, shall be

prefixed with the registered developer identification. All prefix names

shall be registered

(see Annex E). The prefix

“adbe” has been

registered by Adobe Systems and the three subfilter names listed

above and defined in 12.8.3, “Signature Interoperability“ may be used

by any developer.

467

Table 252 - Entries in a signature dictionary (continued)

Key

Type

Value

Contents

byte string

(Required) The signature value. When ByteRange is present, the

value shall be a hexadecimal string

(see

7.3.4.3,

“Hexadecimal

Strings”) representing the value of the byte range digest.

For public-key signatures, Contents should be either a DER-encoded

PKCS#1 binary data object or a DER-encoded PKCS#7 binary data

object.

Space for the Contents value must be allocated before the message

digest is computed. (See 7.3.4, “String Objects“)

Cert

array or

(Required when SubFilter is adbe.x509.rsa_sha1) An array of byte

byte string

strings that shall represent the X.509 certificate chain used when

signing and verifying signatures that use public-key cryptography, or a

byte string if the chain has only one entry. The signing certificate shall

appear first in the array; it shall be used to verify the signature value in

Contents, and the other certificates shall be used to verify the

authenticity of the signing certificate.

If SubFilter is adbe.pkcs7.detached or adbe.pkcs7.sha1, this entry

shall not be used, and the certificate chain shall be put in the PKCS#7

envelope in Contents.

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 array of pairs of integers (starting byte offset, length in

bytes) that shall describe the exact byte range for the digest

calculation. Multiple discontiguous byte ranges shall be 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 253).

Changes

array

(Optional) An array of three integers that shall specify changes to the

document that have been made between the previous signature and

this signature: in this order, the number of pages altered, the number

of fields altered, and the number of fields filled in.

The ordering of signatures shall be 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.

EXAMPLE 1

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.

EXAMPLE 2

A time stamp can be embedded in a PKCS#7 binary

data object (see 12.8.3.3, “PKCS#7 Signatures as

used in ISO 32000”).

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.

EXAMPLE 3

A phone number.

468

Table 252 - Entries in a signature dictionary (continued)

Key

Type

Value

R

integer

(Optional) The version of the signature handler that was used to create

the signature.

(PDF 1.5) This entry shall not be used, and the

information shall be stored in the Prop_Build dictionary.

V

integer

(Optional; PDF 1.5) The version of the signature dictionary format. It

corresponds to the usage of the signature dictionary in the context of

the value of SubFilter. The value is 1 if the Reference dictionary shall

be considered critical to the validation of the signature.

Default value: 0.

Prop_Build

dictionary

(Optional; PDF 1.5) A dictionary that may 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, software build date, version, and operating

system.

he PDF Signature Build Dictionary Specification, 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

authenticated, used in claims of signature repudiation. It should be

omitted if the value is unknown.

Prop_AuthType

name

(Optional; PDF 1.5) The method that shall be used to authenticate the

signer, used in claims of signature repudiation. Valid values shall be

PIN, Password, and Fingerprint.

NOTE 2

The entries in the signature dictionary can be conceptualized as being in different dictionaries; they are in one

dictionary for historical and cryptographic reasons. The categories are signature properties (R, M, Name,

Reason, Location, Prop_Build, Prop_AuthTime, and Prop_AuthType); key information (Cert and portions

of Contents when the signature value is a PKCS#7 object); reference (Reference and ByteRange); and

signature value (Contents when the signature value is a PKCS#1 object).

Table 253 - Entries in a signature reference dictionary

Key

Type

Value

Type

name

(Optional) The type of PDF object that this dictionary

describes; if present, shall be SigRef for a signature

reference dictionary.

TransformMethod

name

(Required) The name of the transform method (see Section

12.8.2,

“Transform Methods”) that shall guide the

modification analysis that takes place when the signature is

validated. Valid values shall be:

DocMDP Used to detect modifications to a document

relative to a signature field that is signed by the

originator of a document; see

12.8.2.2,

“DocMDP.”

UR

Used to detect modifications to a document

that would invalidate a signature in a rights-

enabled document; see 12.8.2.3, “UR.”

FieldMDP Used to detect modifications to a list of form

fields specified in TransformParams; see

12.8.2.4, “FieldMDP.”

TransformParams

dictionary

(Optional) A dictionary specifying transform parameters

(variable data) for the transform method specified by

TransformMethod. Each method takes its own set of

parameters. See each of the sub-clauses specified previously

for details on the individual transform parameter dictionaries

469

Table 253 - Entries in a signature reference dictionary (continued)

Key

Type

Value

Data

(various)

(Required when TransformMethod is FieldMDP) An indirect

reference to the object in the document upon which the object

modification analysis should be performed. For transform

methods other than FieldMDP, this object is implicitly

defined.

DigestMethod

name

(Optional; PDF 1.5 required) A name identifying the algorithm

that shall be used when computing the digest. Valid values

are MD5 and SHA1. Default value: MD5. For security

reasons, MD5 should not be used. It is mentioned for

backwards compatibility, since it remains the default value.

12.8.2

Transform Methods

12.8.2.1

General

Transform methods, along with transform parameters, shall determine which objects are included and excluded

in revision comparison. The following sub-clauses discuss the types of transform methods, their transform

parameters, and when they shall be used.

12.8.2.2

DocMDP

12.8.2.2.1

General

The DocMDP transform method shall be used to detect modifications relative to a signature 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 shall be the first signed field in the document. It

enables the author to specify what changes shall be permitted to be made the document and what changes

invalidate the author’s signature.

NOTE

As discussed earlier, “MDP” stands for modification detection and prevention. Certification signatures that use

the DocMDP transform method 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 12.8.4, “Permissions”).

A certification signature should have a legal attestation dictionary (see 12.8.5, “Legal Content Attestations”)

that specifies all content that might result in unexpected rendering of the document contents, along with the

author’s attestation to such content. This dictionary may 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 254) shall indicate the author’s

specification of which changes to the document will invalidate the signature. (These changes to the document

shall also be prevented if the signature dictionary is referred from the DocMDP entry in the permissions

dictionary.) A value of 1 for P indicates that the document shall be final; that is, any changes shall invalidate the

signature. The values 2 and 3 shall permit modifications that are appropriate for form field or comment

workflows.

12.8.2.2.2

Validating Signatures That Use the DocMDP Transform Method

To validate a signature that uses the DocMDP transform method, a conforming reader first shall verify the byte

range digest. Next, it shall verify that any modifications that have been made to the document are permitted by

the transform parameters.

Once the byte range digest is validated, the portion of the document specified by the ByteRange entry in the

signature dictionary (see Table 252) is known to correspond to the state of the document at the time of signing.

470

Therefore, conforming readers may 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 parameters.

Table 254 - Entries in the DocMDP transform parameters dictionary

Key

Type

Value

Type

name

(Optional) The type of PDF object that this dictionary describes; if present,

shall be TransformParams for a transform parameters dictionary.

P

number

(Optional) The access permissions granted for this document. Valid values

shall be:

1

No changes to the document shall be permitted; any change to the

document shall invalidate the signature.

2

Permitted changes shall be filling in forms, instantiating page

templates, and signing; other changes shall invalidate the signature.

3

Permitted changes shall be the same as for 2, as well as annotation

creation, deletion, and modification; other changes shall invalidate the

signature.

Default value: 2.

V

name

(Optional) The DocMDP transform parameters dictionary version. The only

valid value shall be 1.2.

NOTE

this value is a name object, not a number.

Default value: 1.2.

12.8.2.3

UR

The UR transform method shall be used to detect changes to a document that shall invalidate a usage rights

signature, which is referred to from the UR3 entry in the permissions dictionary (see 12.8.4, “Permissions”).

Usage rights signatures shall be used to enable additional interactive features that may not available by default

in a conforming reader. The signature shall be used to validate that the permissions have been granted by a

bonafide granting authority. The transform parameters dictionary (see Table 255) specifies the additional rights

that shall be 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 shall not be granted.

EXAMPLE

Adobe Systems grants permissions to enable additional features in Adobe Reader, using public-key

cryptography. It uses certificate authorities to issue 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 conforming readers are free to use this

same mechanism for their own purposes.

UR3 (PDF 1.6): The ByteRange entry in the signature dictionary (see Table 252) shall be present. First, a

conforming reader shall verify the byte range digest to determine whether the portion of the document specified

by ByteRange corresponds to the state of the document at the time of signing. Next, a conforming reader shall

examine the current version of the document to see whether there have been modifications to any objects that

are not permitted by the transform parameters.

471

Table 255 - Entries in the UR transform parameters dictionary

Key

Type

Value

Type

name

(Optional) The type of PDF object that this dictionary describes; if present,

shall 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 shall be FullSave, which

permits a user to save the document along with modified form and/or

annotation data. (PDF 1.5) Any usage right that permits the document to be

modified implicitly shall enable the FullSave right.

If the PDF document contains a UR3 dictionary, only rights specified by the

Annots entry that permit the document to be modified shall implicitly enable

the FullSave right. For all other rights, FullSave shall be explicitly enabled in

order to save the document. (Signature rights shall permit saving as part of the

signing process but not otherwise).

If the P entry in the UR transform parameters dictionary is true (PDF 1.6) and

greater conforming readers shall permit only those rights that are enabled by

the entries in the dictionary. However, conforming readers shall permit saving

the document as long as any rights that permit modifying the document are

enabled.

Msg

text

(Optional) A text string that may be used to specify any arbitrary information,

string

such as the reason for adding usage rights to the document.

V

name

(Optional) The UR transform parameters dictionary version. The value shall be

2.2. If an unknown version is present, no rights shall be enabled.

NOTE

This value is a name object, not a number.

Default value: 2.2.

Annots

array

(Optional) An array of names specifying additional annotation-related usage

rights for the document. Valid names (PDF 1.5) are Create, Delete, Modify,

Copy, Import, and Export, which shall permit the user to perform the named

operation on annotations.

The following names (PDF 1.6) shall be permitted only when the signature

dictionary is referenced from the UR3 entry of the permissions dictionary (see

Table 258):

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.

472

Content      ..     10      11      12      13     ..