Introduction to Digital Signatures

This chapter discusses digital signatures and how to apply them to PDF documents.

• About Digital Signatures provides an overview of digital signatures and explains what you can do with them in SecurSign.
• Options for Digital Signatures describes the options for applying digital signatures.

About Digital Signatures

A digital signature is an encrypted message digest — a set of characters that is mathematically generated based on the document being signed, and then encrypted with a private key that belongs to the signer. The digital signature serves two functions. As with a conventional signature, it uniquely identifies the signer. In addition, it indicates whether the document has been modified since it was signed.

Types of digital signatures

You can create two different types of digital signatures on PDF documents using SecurSign:

• An invisible, or blind, signature cannot be seen in the pages of the document. It is only viewable in the Signatures pane as a list of information about the signature. That information includes the signer’s name, time of signing, signature validity, reason for signing, location of signing, document revision number, and signing method. (See the figure below.)

• A visible signature, or signature with appearances, is displayed in the document, as well as in the Signatures pane. The portion that is displayed in the document has two parts: a seal and signature text. (See the examples below.)
  — The seal is a graphic, such as a company logo or a scanned handwritten signature.
  — The signature text is a representation of the information in the Signatures pane.

What you can do with digital signatures

With SecurSign, you can programmatically apply a visible or invisible signature to your documents. For visible signatures, a default seal is supplied; however, any graphic is acceptable for the seal, as long as it is in PDF format (see Creating a Custom Seal). You can apply a visible signature to any existing field in the document (it does not have to be a signature field), or you can create a new signature field anywhere in the document and apply a signature to it simultaneously or at a later time. Whether you use an existing field or create a new one, the seal will scale to fit the field.

Options for Digital Signatures

This section describes the options for digitally signing documents. In addition to the options described here, you can also use the general options discussed in General Options – SecurSign when you apply a digital signature.

Command syntax

$ secursign [options] [-o outFilePath] inPDFFile

Options for digital signatures — summary

Type	Options	Parameter	Description
All Signatures	-sign		Apply a digital signature (default)
	-keypath	<string>	Path to PKCS#12 file
	-keypass	<string>	Password to access key (password to PKCS#12 file)
	-name	<string>	Name of the signer of the PDF document
	-reason	<string>	Reason for signing the file
	-location	<string>	Geographical location of the sign in
	-pdfa		Support the signing of PDF/A documents while retaining PDF/A conformance
	-d	<string>	Owner password to decrypt the file
	-verify		Verify digital signatures on the given PDF document
	-printcert		Print certificate information during signature verification
Visible Signatures/ New Signature Fields	-addfieldonly		Add signature field to document without signing.
	-newsignfield	<string>	Name of new signature field to create.
	-page	<int>	Page number on which to add new signature field.
	-top	<int>	New signature field position-top.
	-left	<int>	New signature field position-left.
	-bottom	<int>	New signature field position-bottom.
	-right	<int>	New signature field position-right.
	-f	<string>	Name of existing field to be signed.
	-seal	<string>	Path to source page containing signature seal.
	-sealpage	<int>	The page in the file identified with -seal on which appears the graphics to be used for the seal.
	-font	<string>	Name of font to be used to draw signature information on the page
	-listfonts		Print a list of the fonts available in the appligent_home fonts directory
	-fontsize	<int>	Font size of signature text.
	-offset	<int>	Signature text offset from left edge of signature rectangle, from 0% to 100%. Default=50%.

Options for all signatures — detailed

-sign — Apply a digital signature (default)

Tells SecurSign to apply a digital signature in accordance with the remaining options on the command line. You can use the -sign option to apply an invisible signature to a document, to apply a visible signature in an existing field, or to simultaneously create a new field and apply a visible signature to it.

• When applying a visible signature to an existing field, you must specify the -f option to identify the field.
• When creating a new field and applying a visible signature to it, you must specify the -newsigfield, -top, -left, -bottom, and -right options to name and position the field.
• The following additional options are required for all types of signature applications: -keypath, -keypass, -name, -location, and -reason. The -d option is required for signing encrypted documents only.

-keypath <string> — Path to key location; required for signing

Path name of the digital ID certificate file that contains the signer’s key. SecurSign supports PKCS#12 certificate files. These files usually have a .p12 extension (such as my_cert.p12) or a .pfx extension (such as my_cert.pfx).

-keypass <string> — Password to access key (password to PKCS#12 file); required for signing

Password associated with the PKCS#12 certificate file. This password must be specified to use the file.

-name <string> — Name of the signer of the PDF file; required for signing

Name of the signer of the document. In most cases this is the signer’s first and last name. If the name includes spaces, it must be enclosed in quotes.

-reason <string> — Reason for signing the file; required for signing

Reason for signing the file. This can be kept short, for instance, “Company security requirement.”

-location <string> — Geographical location of the signing; required for signing

Where the signing took place. In the United States, this may be kept to city, state, and country (for example, “Lansdowne, PA, USA”). In other countries, enough detail should be included so that readers of the document will understand where it is from (for example, “Paris, France” or “Erdington, West Midlands, England”). If the location includes spaces, it must be enclosed in quotes.

-pdfa — Support PDF/A documents

PDF/A documents can be digitally signed while retaining conformance for PDF/A.

-d <string> — Owner password of encrypted input file; required if input file is encrypted

The current Owner password of a document that is already encrypted. Supplying the Owner password enables you to add or change encryption options.

-verify — Verify digital signatures on the given PDF document

Determine the integrity of all of the digital signatures applied to the PDF document.  Also, determine if the file has been modified by appending information to the end of the file after the document has been digitally signed.  Any problems found write information to the log and return a non-zero result in the status.

-printcert — Print certificate information during signature verification

Detailed digital signature data along with certificate information is printed to the console during signature verification.

Options for visible signatures / new signature fields — detailed

-addfieldonly — Add signature field to document without signing

Instructs SecurSign to add a signature field to a document. You can use this option to create a new signature field, but you cannot use it to simultaneously create and sign a new signature field. If you specify the -addfieldonly option, you must also specify the -newsigfield, -top, -left, -bottom, and -right options to name and position the field.

-newsigfield <string> — Name of new signature field

Name of a new signature field to be created in a document. You can use the -newsigfield option with the -sign option to simultaneously create the field and apply a visible signature to it, or with the -addfieldonly option to just create the field for signing at a later time. If you specify the -newsigfield option, you must also specify the -top, -left, -bottom, and -right options to position the field.

-page <int> — Page number on which to add new signature field (default=1)

Number of the page on which you want to add a new signature field. If you specify the -page option, you must also specify the -newsigfield, -top, -left, -bottom, and -right options.

-top <int> — New signature field position — top; required with -newsigfield

Location of the top of a new rectangular signature field, measured from the bottom of the uncropped page. Specify the location as a floating-point decimal measured in points, for example, 115, 115.2, or 115.25.  If you specify the -top option, you must also specify the -newsigfield, -left, -bottom, and -right options. The figure below shows the -top, -left, -bottom, and -right options for a signature field positioned on an 8-1/2 x 11-inch page.

-left <int> — New signature field position — left; required with -newsigfield

Location of the left side of a new rectangular signature field, measured from the left side of the uncropped page. Specify the location as a floating-point decimal measured in points, for example, 90, 90.4, or 90.45.  If you specify the -left option, you must also specify the -newsigfield, -top, -bottom, and -right options. (See the figure below.)

-bottom <int> — New signature field position — bottom; required with -newsigfield

Location of the bottom of a new rectangular signature field, measured from the bottom of the uncropped page. Specify the location as a floating-point decimal measured in points, for example, 20, 20.1, or 20.15.  If you specify the -bottom option, you must also specify the -newsigfield, -top, -left, and -right options. (See the figure below.)

-right <int> — New signature field position — right; required with -newsigfield

Location of the right side of a new rectangular signature field, measured from the left side of the uncropped page. Specify the location as a floating-point decimal measured in points, for example, 440, 440.3, or 440.35.  If you specify the -right option, you must also specify the -newsigfield, -top, -left, and -bottom options. (See the figure below).

-f <string> — Name of existing field to be signed

Name of an existing field in which to place a visible signature. You can use any existing form field in the document. It doesn’t have to be a signature field.

-seal <string> — Path to PDF document containing signature seal (default=default_seal.pdf)

Path name of the PDF file containing the seal to be used for a visible signature. The file must be in PDF format. If you do not specify the -seal option, default_seal.pdf will be used. The default-seal.pdf file supplied with SecurSign is shown to the right. You can replace this file with your own seal file named default_seal.pdf.

-sealpage <int> — Source page containing signature seal (default=1)

Page on which the seal for a visible signature is located in the file named with the -seal option. If you specify the -sealpage option, you must also specify the -seal option.

-font <string> — Font to be used to draw Digital Signature appearance

You have the ability to specify an OpenType font  when signing a document.  The fonts need to be placed into the Font directory located in the appligent_home  directory. On Windows, the location is C:\Documents and Settings\All Users\Application Data\Appligent\APDFLX.X.X\Resource\Font.  On Unix the location is /usr/local/appligent/APDFLX.X.X/Resource/Font.   Any number of additional fonts can be placed in the appligent_home  directory. Use the -listfonts command to determine the proper font name.

-listfonts — Print a list of available font located in the appligent_home directory

Font names are not always the name of the file.  -listfonts will return a list of all available fonts SecurSign can use that are located in the appligent_home directory.

-fontsize <int> — Font size of signature text (default=12)

Font size, in points, of the signature text that is part of a visible signature. This includes the text specified in the -name, -reason, and -location options, as well as the date and time of signing.

-offset <int> — Signature text offset from left edge of signature rectangle (default=50)

Distance between the left edge of the signature field and the left edge of the signature text, specified as a percent of the field length. You may specify an integer value from 0 to 100 (the default is 50). For example, if the field length is 280 points and the -offset is 50, the signature text starts 140 points from the left edge of the field.