Acrobat Digital Signature API Reference - Adobe Partners

c 

Acrobat Digital 

Signature API 

Reference 

Technical Note #5192 

Version: Acrobat 6.0 

ADOBE SYSTEMS INCORPORATED 

Corporate Headquarters 

345 Park Avenue 

San Jose, CA 95110-2704 

(408) 536-6000 

http://partners.adobe.com 

May, 2003

Copyright 2003 Adobe Systems Incorporated. All rights reserved. 

NOTICE: All information contained herein is the property of Adobe Systems Incorporated. No part of this publication (whether in hardcopy or 

electronic form) may be reproduced or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or 

otherwise, without the prior written consent of the Adobe Systems Incorporated. 

PostScript is a registered trademark of Adobe Systems Incorporated. All instances of the name PostScript in the text are references to the 

PostScript language as defined by Adobe Systems Incorporated unless otherwise stated. The name PostScript also is used as a product 

trademark for Adobe Systems’ implementation of the PostScript language interpreter. 

Except as otherwise stated, any reference to a “PostScript printing device,” “PostScript display device,” or similar item refers to a printing device, 

display device or item (respectively) that contains PostScript technology created or licensed by Adobe Systems Incorporated and not to devices 

or items that purport to be merely compatible with the PostScript language. 

Adobe, the Adobe logo, Acrobat, the Acrobat logo, Acrobat Capture, Distiller, PostScript, the PostScript logo and Reader are either registered 

trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. 

Apple, Macintosh, and Power Macintosh are trademarks of Apple Computer, Inc., registered in the United States and other countries. PowerPC 

is a registered trademark of IBM Corporation in the United States. ActiveX, Microsoft, Windows, and Windows NT are either registered 

trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. UNIX is a registered trademark of The Open 

Group. All other trademarks are the property of their respective owners. 

This publication and the information herein is furnished AS IS, is subject to change without notice, and should not be construed as a 

commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies, 

makes no warranty of any kind (express, implied, or statutory) with respect to this publication, and expressly disclaims any and all warranties 

of merchantability, fitness for particular purposes, and noninfringement of third party rights.

Acrobat SDK Documentation Roadmap 

Getting Started 

Getting Started Using the Acrobat Software Development Kit 

Acrobat SDK Release Notes Acrobat Developer FAQ Reader Enabling 

Acrobat Development Overview Acrobat Plug-in Tutorial Acrobat SDK Samples Guide 

PDF Specification 

PDF Reference 

Manual 

Upgrading Plug-ins from Acrobat 5.0 to Acrobat 6.0 

Acrobat Core API 

Acrobat Core 

API Overview 

Extended API for Plug-in 

AcroColor API Reference 

PDF Creation APIs 

and Specifications 

Acrobat Distiller 

Parameters 

JavaScript 

Acrobat JavaScript 

Scripting 


Acrobat Interapplication 

Communication (IAC) 

Acrobat IAC Overview 

Acrobat Core 

API Reference 

ADM Programmer’s 

Guide and Reference 

Acrobat Distiller 

API Reference 

Acrobat 

JavaScript 

Scripting Guide 

Acrobat IAC Reference 

Catalog API Reference 

Digital Signature API 


pdfmark 


Programming 

Acrobat JavaScript 

Using Visual Basic 

Forms API Reference 

PDF Consultant 

Accessibility Checker 

Search API Reference 

Spelling API Reference 

Using the Save as 

XML Plug-in 

Weblink API Reference

Contents 

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 

What Is in This Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 

Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 

Other Useful Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 

Conventions Used in This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 

Chapter 1 Digital Signature Overview . . . . . . . . . . . . . . . . . . . . . 15 

Plug-in Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 

The PubSec Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 

Digital Signature Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 

Digital Signature Scenarios. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 

Initializing a Plug-in to Work With the Digital Signature Plug-in. . . . . . . . . . . . . . . . . . . . 17 

Handling Document Open and Close Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 

Understanding the Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 

Dialogs and Signature Gathering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 

Saving a Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 

Finishing the Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 

Revalidating Signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 

Additional Available Callbacks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 

Additional DigSig Plug-in Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 

Rollback Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 

Chapter 2 PubSec Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 

General PubSec Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 

PSCertIssuedUnderTestCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 

PSCloseEncryptedDocs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 

PSCountEncryptedDocs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 

PSDataBufferDigest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 

PSDataBufferEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 

PSExportDataExchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 

PSImportDataExchange. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 

PSRegisterHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 

PSSigValidatePDDocSigField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 

Acrobat Digital Signature API Reference 5

Contents 

PSUnregisterHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 

PubSec Acrobat Address Book Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 

AABFindCertsByName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 

AABGetCertChain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 

AABGetCertTrust . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 

AABGetTrustedCerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 

AABIsCertPresent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 

Digital Signature Appearance File Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 

DSAPFileAcquire . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 

DSAPFileCanDeleteNthEntry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 

DSAPFileCopyNthEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 

DSAPFileEditNthEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 

DSAPFileGetCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 

DSAPFileGetNewNthName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 

DSAPFileRelease . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 

DSAPFileRemoveNthEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 

DSAPFileSave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 

Chapter 3 PubSec Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 

PSDestroyEngineProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 

PSExportDataProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 

PSGetAtomPropertyProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 

PSGetBoolPropertyProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 

PSGetDirHandlerInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 

PSGetDirInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 

PSGetDirList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 

PSGetImplicitRecipientsProc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 

PSGetInt32PropertyProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 

PSGetLogoProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 

PSGetTextPropertyProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 

PSImportDataProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 

PSNewEngineProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 

PSOpenCMSEnvelopeProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 

PSOpenConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 

PSPerformOperationProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 

PSSessionAcquireProc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 

PSSessionReadyProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 

PSSessionReleaseProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 

PSSetDirInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 

PSSigAuthenticateProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 

PSSigCreateAPNXObjProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 

PSSigGetSigPropertiesProc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 

PSSigGetSigValueProc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 

PSSigPropDialogProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 

PSSigValGetAPLabelProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 

6 Acrobat Digital Signature API Reference

Contents 

PSSigValGetTextProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 

PSSigValidateDialogProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 

PSSigValidateProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 

PSSigValidateSupportedProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 

Chapter 4 PubSec Declarations . . . . . . . . . . . . . . . . . . . . . . . . . 79 

APPreview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 

DirAuthenticationContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 

DirConnection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 

DirectoryInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 

DirectoryList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 

DirectoryInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 

DirHandlerInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 

DSAPFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 

DSDigestMethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 

DSPropertyType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 

DSRetCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 

DSSaveType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 

DSSigValText. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 

PSAPSigType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 

PSDataBuffer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 

PSExportDataExchangeParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 

PSExportDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100 

PSExportDestType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101 

PSImportDataExchangeParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102 

PSImportDataParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103 

PSImportDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104 

PSOpenCMSEnvelopeParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105 

PSPerformOpType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106 

PSSessionOpType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107 

PSSigCosDocParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109 

PSSigDataBufferParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110 

PSSigDocType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111 

PSSigDialogStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112 

PSSigFileType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113 

PSSigMethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114 

PSSigPDDocParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115 

PSSigGetSigValueParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116 

PSSigSigPropParams. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118 

PSSigTrust . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120 

PSSigValidateParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121 

PSSigValidateDialogParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123 

PSSigValidateSupportParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125 

PSSigValSupport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126 

PubSecEngine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127 

PubSecHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128 


Contents 

Chapter 5 Digital Signature Methods . . . . . . . . . . . . . . . . . . . . . 133 

DigSigAddedSig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133 

DigSigAddedSigEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134 

DSAPCreateCompositeTextXObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135 

DigSigAPCreateLayeredStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136 

DigSigAPCreateLayeredStreamEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138 

DigSigAPXObjectFromLogo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139 

DigSigAPXObjectFromXObjList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140 

DigSigByteToHex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141 

DigSigClearSig. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142 

DigSigClearSigRefDict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143 

DigSigClick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144 

DigSigCommitSigRefDict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145 

DigSigComparePages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146 

DigSigComparePagesEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147 

DigSigCompareWords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148 

DigSigCompareWordsAndFontsRecent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149 

DigSigCompareWordsEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150 

DigSigCompareWordsRecent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151 

DigSigCosObjOverwrite. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152 

DigSigCreateStdXObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154 

DigSigDeletedSig. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155 

DigSigDeletedSigEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156 

DigSigDocModifiedAfterSig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157 

DigSigDoProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158 

DigSigDraw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159 

DigSigEnumSignatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160 

DigSigFileGetEOF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161 

DigSigFileRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162 

DigSigFileSetPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163 

DigSigFinishSigRefDict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164 

DigSigGetDocAuthorSignature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165 

DigSigGetDocMDPSetting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166 

DigSigGetStdXObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167 

DigSigGetUbiquitySignature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168 

DigSigGetUniqueTitle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169 

DigSigHexToByte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170 

DigSigIsDocSigned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171 

DigSigIsSigSigned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172 

DigSigKeyDown. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173 

DigSigMD5ByteRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .174 

DigSigNewSigRefDict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175 

DigSigOverwriteBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176 

DigSigOverwriteHexstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177 

DigSigOverwriteIntArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178 

DigSigRegisterFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179 


Contents 

DigSigRegisterObserver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .180 

DigSigRightClick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181 

DigSigRollbackToSig. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182 

DigSigSignDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183 

DigSigUnregisterFilter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184 

DigSigUnregisterObserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185 

DigSigUpdatePanel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186 

DigSigVerifySig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187 

DigSigVerifySigRefDict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188 

Chapter 6 Digital Signature Callbacks . . . . . . . . . . . . . . . . . . . . 189 

DigSigEnumProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189 

DSCanValidateProc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190 

DSClearSigProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191 

DSCommitSignProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .192 

DSDefaultValueProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193 

DSDocCloseProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194 

DSDocOpenProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195 

DSFinishSignProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196 

DSFreeSigDataProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197 

DSGetBoolPropertyProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .198 

DSGetSigPropProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199 

DSGetStatusTextProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200 

DSGetValidStateProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201 

DSNewSigDataProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .202 

DSNewSigDataWithParamsProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .203 

DSNotificationProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204 

DSNotificationFailureProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205 

DSPropertiesProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206 

DSPropertiesExProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207 

DSReValidateSigProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .208 

DSSigDataGetErrorTextProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209 

DSUnValidateSigProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .210 

DSValidateSigProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211 

Chapter 7 Digital Signature Declarations. . . . . . . . . . . . . . . . . . . 215 

DigSigBBox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215 

DigSigHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .216 

DigSigNewSigDataParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219 

DigSigOffset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221 

DigSigOffsetRec. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221 

DSAPCreateLayeredStreamExParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222 

DSAPTextEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224 

DSAPXObjEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225 


Contents 

DSAPXObjEntryRec. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225 

DSComparePagesParams. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227 

DSCompareWordsParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228 

DSHandlerProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229 

DSMDPType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230 

DSNotificationType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231 

DSNotifyParams. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233 

DSOverwriteType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234 

DSQuadding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .235 

DSSigRefDictErrParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236 

DSSigRefDictParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237 

DSSigRefErrCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .238 

DSValidState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239 

DSXObjType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .240 

Chapter 8 Digital Signature’s Use of Core API Objects . . . . . . . . . . . 241 

ASAtom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241 

ASCab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241 

ASFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241 

ASText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241 

AVPageView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241 

CosDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241 

CosObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241 

PDAnnot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242 

PDDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242 


Preface 

Digital signatures allow a person to attest to something about a document by signing their 

name to it. An Acrobat signature in a document is bound to that document in such a way 

that altering the signed document or moving the signature to a different document 

invalidates the signature. 

A single document may be signed more than once, and changes may occur between 

signings. Acrobat’s Digital Signatures links each signature with a particular state of the 

document. All changes append the PDF changes to the fully-preserved base PDF 

document. The ability to do serial signatures of protected documents is unique to Acrobat, 

and draws heavily on the PDF file design for an appended save. 

Adobe Acrobat implements digital signatures using plug-ins that can handle both generic 

functions common to all digital signatures, and also specific kinds of signatures (signing 

methods), such as public-private key (PPK), handwriting, retinal scans, fingerprints, and so 

forth. 

If you received this technical note without obtaining the entire Acrobat Software 

Development Kit (SDK), you can get the complete SDK by visiting: 

http://partners.adobe.com/asn/developer/acrosdk/main.html 

What Is in This Document 

This document provides a reference for the methods, callbacks declarations and objects 

used in creating digital signatures. This document contains separate sections on each: 

● Digital Signature Overview provides a general overview of how to work with the digital 

signature plug-in. 

● PubSec Methods provides detailed descriptions of the methods and structures in the 

PubSec access layer, which forms a high-level interface to the digital signature facility. 

● PubSec Callbacks provides detailed description of PubSec callback functions, which the 

Acrobat viewer and Library use to invoke functionality provided by plug-ins and 

applications. 

● PubSec Declarations provides detailed descriptions of data declarations used in the 

PubSec access layer. 

● Digital Signature Methods provides detailed descriptions of each method, including its 

parameters and return value. 

● Digital Signature Callbacks provides detailed description of callback functions, which 

the Acrobat viewer and Library use to invoke functionality provided by plug-ins and 

applications. 


Preface 

Audience 

● 

● 

Digital Signature Declarations provides detailed descriptions of data structures used by 

the Acrobat viewer and Library. 

Digital Signature’s Use of Core API Objects provides a list of objects used by the Digital 

Signatures plug-in. This list enables you to easily find in the Core API Reference objects 

you will probably use while creating your plug-in.. 

Audience 

You should read this document if you are a security developer who wants to extend your 

security measures to your customers’ PDF documents. This document assumes that you are 

writing plug-ins to customize Acrobat’s Digital Signature capabilities to your customers’ 

needs. 

Prerequisites 

You should already be familiar with the process for creating Acrobat plug-ins. If you are not, 

please read the Acrobat Plug-In Tutorial. 

Other Useful Documentation 

The Acrobat SDK includes many other books that you might find useful. When mentioned 

in this document, those books will often appear as live links (blue italic links). However, in 

order to actually jump from this document to those books, those books must exist in the 

proper directories within your computer's file system. This happens automatically when 

you install the SDK onto your system. 

If for some reason you did not install the entire SDK onto your system and you do not have 

all of the documentation, please visit the Adobe Solutions Network web site 

(http://partners.adobe.com/asn) to find the books you need. Then download them and 

install them in the proper directories, which can be determined by looking at the Acrobat 

SDK Documentation Roadmap, included at the beginning of each book in the SDK. 

You should be familiar with the Acrobat core API and Portable Document Format (PDF). The 

following technical notes provide this information. 

Acrobat Core API Overview, Technical Note #5190. Gives an overview of the objects and 

methods provided by the Acrobat core API. 

Acrobat Core API Reference, Technical Note #5191. Describes in detail the objects and 

methods provided by the Acrobat core API. 

PDF Reference, Fourth Edition, version 1.5. Provides a description of the PDF file format, as 

well as suggestions for producing efficient PDF files. It is intended for application 

developers who wish to produce PDF files directly. 


Preface 

Conventions Used in This Book 


The Acrobat documentation uses text styles according to the following conventions. 

Font Used for Examples 

monospaced Paths and filenames C:\templates\mytmpl.fm 

monospaced bold 

Code examples set off 

from plain text 

Code items within plain 

text 

Parameter names and 

literal values in 

reference documents 

These are variable declarations: 

AVMenu commandMenu,helpMenu; 

The GetExtensionID method ... 

The enumeration terminates if proc 

returns false. 

monospaced italic Pseudocode ACCB1 void ACCB2 ExeProc(void) 

{ do something } 

Placeholders in code 

examples 

AFSimple_Calculate (cFunction, 

cFields) 

blue Live links to Web pages The Acrobat Solutions Network URL is: 

http://partners/adobe.com/asn/ 

bold 

italic 

Live links to sections 

within this document 

Live links to other 

Acrobat SDK documents 

Live links to code items 

within this document 

PostScript language and 

PDF operators, 

keywords, dictionary 

key names 

User interface names 

Document titles that are 

not live links 

New terms 

PostScript variables 

See Using the SDK. 

See the Acrobat Core API Overview. 

Test whether an ASAtom exists. 

The setpagedevice operator 

The File menu 

Acrobat Core API Overview 

User space specifies coordinates for... 

filename deletefile 


Preface 



1 

Digital Signature Overview 

Plug-in Relationships 

The following figure illustrates the security plug-in relationships. 

Adobe Acrobat 

Acrobat API 

PDCrypt 

LegalPDF 

Scrubber Agent 

(plug-in) 

DigSig (plug-in) 

DigSigHFT 

PubSec 

PubSecHFT 

Self-Sign 

(PPKLite Handler) 

MSCAPI and ADSI 

interface 

(PPKMS Handler) 

Acrobat Address Book 

(AAB Handler) 

3rd party 

PubSec 

handlers 

PKCS#12 

File 

Microsoft OS 

CSP CSP CSP ... 

User 

Contact 

File 

The PubSec Layer 

The PubSec layer, introduced in Acrobat 6.0, is an interface for Acrobat public-key security 

handlers. PubSec forms a high-level interface to the digital signature facility; the PubSec 

code uses DigSig for digital signature operations, but provides many additional benefits. 

Developers are encouraged to use the PubSec HFT rather then DigSig HFT. 


1 


Digital Signature Components 

PubSec provides functions to: 

● 

● 

● 

Count and close encrypted documents. 

Validate a specific signature field. 

Access and create digests for data buffers. 

● Import and export certificate data, and manage the certificates in the Acrobat Address 

Book (AAB). 

● Manage signature appearances (DSAP files). 

● Register and unregister handlers. Handlers can register as PubSec handlers to provide 

the following cryptographic services: 

– Do private-key signing and signature validation 

– Act as a cryptographic source for decrypting using private keys 

– Act as a directory source for certificate-based identity authentication 

Handlers can call back into the PubSec HFT for various services. Most calls to PubSec pass 

an opaque state object called a PSEngine. You specify a default engine upon registering the 

handler, and the default engine can make use of the security UI dialogs provided by PubSec 

and DigSig. 

To register a handler with PubSec: 

1. Implement the callbacks you need to provide customized functionality. Many of the 

callbacks for PubSec can be specified as NULL, in which case PubSec provides default 

behavior. It is recommended that you use the default behavior when possible. 

2. Fill in the handler structure with pointers to your callback implementations 

(PubSecHandler). 

3. Register the handler with PubSec (PSRegisterHandler). 

Digital Signature Components 

Digital signatures contain two parts: 

● The signature field dictionary: the PDF dictionary structure that stores information 

about the signature 

● The signature annotation with its associated appearance (including the background, 

and layout of name, time, and so on). A blind digital signature does not have an 

associated appearance. 

Acrobat’s Digital Signature plug-in creates these two parts when the user chooses to sign a 

document. Your plug-ins do not have to handle deleting the signature, as the DigSig plugin 

does that transparently. 



Digital Signature Scenarios 

1 

Digital Signature Scenarios 

Acrobat supports three digital signature scenarios. Acrobat’s Digital Signature plug-in 

handles the first case, and allows other plug-ins to further handle the second and the third 

cases. 

1. If the user creates a signature field and does not specify a default signing method, 

DigSig handles that case with no communication to your plug-ins: 

– DigSig creates the signature field dictionary. 

– DigSig creates the signature annotation dictionary. 

– DigSig creates the (blank) signature appearance dictionary. 

2. The Forms plug-in also creates Signature fields. If the user creates a signature field and 

specifies a default method, Forms calls DigSig to fill in default values: 

– DigSig creates the signature field dictionary, the signature annotation dictionary, and 

the (blank) signature appearance dictionary. 

– DigSig calls the DSDefaultValueProc callback that your plugin provides. This 

callback must create the default signature value dictionary and create the /DV key in 

the signature field dictionary to point to it. 

3. If the user asks to sign a specific signature field using the plug-in, DigSig calls callbacks 

into your plug-in in four-step sequence. Your plug-in must register these callbacks 

during the plug-in initialization phase. The four callbacks required for this scenario are: 

– dsNewSigData 

– dsCommitSign 

– dsFinshSign 

– dsFreeSigData. 

Initializing a Plug-in to Work With the Digital Signature Plug-in 

When Acrobat launches, all plug-ins go through a three-step initialization process that 

allows plug-ins to establish communication among themselves without being dependent 

on the order of loading. For plug-ins that interact with Acrobat’s Digital Signature plug-in 

(DigSig), use the following intialization sequence: 

1. Export Host Function Tables (HFTs). DigSig exports its HFT under the name DigSigHFT. 

2. Import HFTs. To work with DigSig, your plug-in must import the DigSig HFT. 

3. Perform initialization. To work with DigSig, your plug-in must create a 

DigSigHandlerRec structure, assign the relevant methods, and then call 

DigSigRegisterFilter to register the structure. 


1 


Understanding the Process 

Handling Document Open and Close Operations 

When the user opens a document, DigSig calls your plug-ins to notify them of the new 

document by calling DSDocOpenProc; you might allocate some storage or choose to 

automatically validate any of their respective signatures in the document. 

Auto-validation may produce significant delays if it must read all of a large document from 

a CD-ROM or over a network, or if it must access a signature registry or authority over a 

network. Therefor, Adobe software only accesses signatures at user request. 

When the user closes a document, DigSig calls DSDocCloseProc. 


The steps in this section are suggestions that describe the interactions of a digital signature 

plug-in. (The SignDoc sample plug-in provided with this SDK is a more complete 

example.) 

Dialogs and Signature Gathering 

1. DigSig calls your dsNewSigDataProc, a callback that begins the process. 

– Your plug-in interacts with the user, and allows the user to cancel if they want to do so. 

– Your plug-in acquires the signature itself in a method-specific way. All information is 

saved in memory, without altering the document itself. This allows a later backout. 

– If dsNewSigData does not cancel, DigSig prepares the document for saving: It first 

calls dsUnValidateSig on every signature in the document to put any 

overprinting/underprinting in canonical form. It then counts how many pages and 

fields have changed since any prior signature and records this. 

– For a first signature, DigSig does the SaveAs dialog, allowing the user to select 

filename, optimization, and encryption. The user may cancel. Other than fatal errors, 

such as out-of-disk-space, this is the last chance to stop the process. 

Saving a Document 

1. DigSig calls Xxxx.DSCommitSignProc to update the document with the actual 

signature. 

Your DSCommitSignProc callback must: 

– create the signature dictionary, possibly using information in the signature field /DV 

dictionary, perhaps using the /ByteRange and /Contents keys. 

– point /V in the signature field dictionary to this. Then create the /AP /N value in the 

signature annotation dictionary, using a method-specific visible representation of the 

signature, including a symbol signifying “unvalidated signature.” 

– optionally allocate dynamic storage for a marked array, an array of “marked” COS 

objects that it cares about. 




1 

– return a marked array that includes at least the /ByteRange and /Contents value 

objects. 

2. DigSig inserts the /Changes array from step 1. 

3. DigSig saves the PDF document to a file. For each Cos object in the marked array, DigSig 

records the object’s byte offset and length in the file as written. The saved file may have 

objects encrypted by the Acrobat standard encryption handler, if the user so chooses. 

4. The very first time a document is signed, DigSig may rename the file and may invoke the 

Optimizer, Linearizer, and Garbage Collector. Upon return from the save, all COS objects 

are invalid, including those in the marked array. 

– All PD-level objects except the PDDoc are invalid. Signing methods must not depend 

on saving any such state between dsCommitSign and dsFinishSign. In 

particular, the byte offsets and lengths in the marked array are valid upon entry to 

doSign, but the Cos objects are not. The order of entries is unchanged, however, 

these Cos objects will be rewritten by DigSig as CosNull before calling 

dsFinishSign. 

Finishing the Process 

1. DigSig calls dsFinishSign, passing back in the marked array. 

Your DSFinishSignProc must: 

– Calculate the /ByteRange that it desires, using the byte offsets and lengths in the 

marked array. 

– Overwrite the marked /ByteRange value in the saved file, using the 

DigSigOverwriteIntArray or DigSigOverwriteBytes callback. 

– Overwrite any other marked Cos objects it wants to. 

– Calculate any document digest that it desires, using the DigSigFileGetEOF, 

DigSigFileSetPos, and DigSigFileRead callbacks; or it may use the 

DigSigMD5ByteRange callback. 

– Obscure or encrypt this digest in a method-specific way. 

– Overwrite the marked /Contents value in the saved file, using 

DigSigOverwriteHexstring or DigSigOverwriteBytes. 

– Optionally delete dynamic storage for the marked array the plug-in returns. 

2. DigSig calls dsFreeSigData, which may free up any remaining storage. 


1 



Revalidating Signatures 

If the user reopens the file, the signatures must be revalidated. If the user asks to validate 

one or more signature fields, DigSig sequences through them one at a time: 

1. DigSig calls validateSign. Your DSValidateSignProc must: 

– Recalculate any document digest that it desires, using the DigSigFileGetEOF, 

DigSigFileSetPos, and DigSigFileRead callbacks; or it may use the 

DigSigMD5ByteRange callback. 

– Compar this result to the stored one, and do any other method-specific checks it 

desires. 

– Optionally do a validation against some stored (network) registry. 

– Update the /AP /N value in the signature annotation dictionary to show 

doublechecked/pass/fail symbol. 

– Return doublechecked/pass/fail. 

The user may open more than one document at a time, and may switch between open 

documents at will. 

Additional Available Callbacks 

The user may ask to show a signature panel containing summary information for each 

signature in an open document. If multiple documents are open, there may be multiple 

panels, or a single panel may be repainted as the user switches between documents. DigSig 

manages updating the panel(s), but may call the respective method plug-in for each 

signature to get information to display on the panel. For each signature, the signature 

panel has two levels of detail: 

1. CLOSED displays a doublechecked/pass/fail/unknown/blank icon and a line 

of text for each signature field in the document. The default text is the name of the 

person signing and the date and time of signing, displayed in a language-independent 

way. 

2. DigSig calls dsGetValidState to choose which icon to show. 

3. OPEN displays an icon and line of text for each signature, then indented lines of further 

text, currently consisting of the name of the signer, date and time of signing, location of 

signing, reason for signing, and signing method. 

4. DigSig calls dsGetValidState to choose which icon to show. 

Your plug-in may update the signature panel for a document asynchronously (it might be 

doing validation as a background or idle-loop task). To do this, use the 

DigSigUpdatePanel callback. 




1 

Additional DigSig Plug-in Support 

Whenever a signature is created or verified, the plug-in may optionally alter the appearance 

of the signature in the document, for the purpose of displaying or printing. For example, it 

could change an overprinted question mark on an unverified signature to an underprinted 

logo for a verified signature. To help with this, DigSig provides an HFT callback 

DigSigGetStdXObj that returns an XObject for a blank appearance, a question mark, 

or a cross. These are suitable as targets of the Do operator in a signature’s appearance 

stream. 

To avoid saving a signature to a file with an appearance of valid (rather than unvalidated), 

just before each file save, DigSig loops through all the signature fields and calls the specific 

method’s dsUnValidateSig entry. This routine restores the signature’s appearance to 

the unvalidated state. 

The AcroForms Widget Annothandler calls into DigSig using four entries. These calls all 

reflect user actions taken in the document view, not the Signatures panel view. 

When the user selects an annotation by tabbing to it or by clicking it with the mouse, and 

that annotation is for a signature field, AcroForms calls DigSigDraw. If the annotation is 

selected, then bIsSelected is true. 

When the user tabs to a signature annotation and activates it by hitting the spacebar or 

enter key, this is equivalent to a left mouse click. 

AcroForms calls DigSigKeyDown. The parameters parallel those of 

AVAnnotHandlerDoKeyDownProc. 

When the user left-clicks inside a signature annotation, AcroForms calls DigSigClick. 

The parameters parallel those of DoClickProcType. 

When the user right-clicks inside a signature annotation, AcroForms calls 

DigSigRightClick. 

Rollback Support 

There is a constraint on the values in the /ByteRange array. This constraint allows DigSig to 

implement rollback to prior signatures: 

The largest offset + length value in the /ByteRange array for a given signature must be 

equal to the length of the PDF file containing that signature; that is, it must equal offset + 1 

of the "F" in the %%EOF at the end of the file. 

In addition, the following constraints also apply: 

● All offsets must be in the range 0..2147483647 

● All lengths must be in the range 1..2147483647 

● Offset[n+1] must be strictly greater than offset[n] + length[n] 


1 




2 

PubSec Methods 

These methods form a high-level interface to the digital signature facility. Methods are 

presented in the following groups: 

● General PubSec Methods 

● PubSec Acrobat Address Book Methods 

● Digital Signature Appearance File Methods 

General PubSec Methods 

PSCertIssuedUnderTestCP 

ASBool PSCertIssuedUnderTestCP (ASCab inCertChain); 

Description 

Tests whether any certificate in a chain has been issued under the Adobe Test Certificate 

Policy. 

If this function returns true, PubSec handlers are recommended to provide feedback to 

the user regarding the test nature of the certificate, which may render it untrustworthy. 

Parameters 

inCertChain 

The certificate chain to test, as an ASCab array. The first certificate is 

the end entity, and certificates should follow in the issuing order. For 

example: 

{ ("0", cert1), ("1", cert2), ... } 

where certn is an X509 certificate as ASN1-encoded binary data. 

Return Value 

true if any certificate in the chain was issued under the Adobe Test Certificate Policy, 

false otherwise. 

Header File 

PubSecHFT.h 


2 



PSCloseEncryptedDocs 

ASBool PSCloseEncryptedDocs (PubSecEngine engine); 

Description 

Closes all encrypted documents associated with a PubSec engine, regardless of whether 

they need to be saved or not. Use PSCountEncryptedDocs to determine if there are 

any documents that will need to be opened or saved. 

PubSec keeps a list of all open encrypted documents. For security reasons, handlers will 

want all of these documents to be closed when it releases access to critical resources, for 

example when logging out. Use this method (rather than closing the documents directly) 

so that PubSec can maintain its cache correctly. 

Parameters 

engine 

The engine for which the encrypted docs are closed. 

Return Value 

true if successful, false otherwise. 

Header File 

PubSecHFT.h 

Related Methods 

PSCountEncryptedDocs 




2 


void PSCountEncryptedDocs (PubSecEngine engine, 

ASUns32 *outNeedSave, ASUns32 *outCanClose); 

Description 

Returns the number of encrypted documents associated with a PubSec engine. Returns 

separate values for documents that need to be saved, and for those that do not need to be 

saved and can be safely closed. 

Parameters 

engine 

outNeedSave 

outCanClose 

The engine for which the encrypted docs are counted. 

(Filled by the method) A pointer to the number of encrypted 

documents associated with the engine that need to be saved. 

(Filled by the method) A pointer to the number of encrypted 

documents associated with the engine that do not need to be saved 

and can be safely closed. 

Return Value 

None 

Header File 

PubSecHFT.h 




2 



PSDataBufferDigest 

ASBool PSDataBufferDigest (PSDataBuffer dataBuffer, 

ASUns8* digestValue, DSDigestMethod digestMethod); 

Description 

Computes the digest for a set of data. A handler will use this call to make PubSec compute 

the digest for a data buffer when signing or verifying signatures. This method calls 

PSDataBufferEnum to get the bytes and computes an MD5 or SHA-1 digest. 

Parameters 

dataBuffer 

digestValue 

digestMethod 

The buffer containing the data. 

(Filled by the method) A pointer to the digest value. The buffer 

must large enough for the requested digest method: 

● For an MD5 digest, it must be at least 16 bytes. 

● For an SHA-1 digest, it must be at least 20 bytes. 

The method to use to compute the digest. 

Return Value 


Header File 

PubSecHFT.h 


PSDataBufferEnum 




2 


ASBool PSDataBufferEnum (PSDataBuffer dataBuffer, 

ASInt32 maxSize, ASUns8 **pReturnBuffer, 

ASInt32 *pReturnSize); 

Description 

Gets bytes of data to digest when signing or verifying, in chunks of a specified size. 

Continues getting data chunks until all of the data in the data buffer has been returned. 

A handler will use this call when computing its own data digest, to get the next blob of 

bytes to digest. The dataBuffer object keeps track of the bytes that have been returned, 

of how many bytes remain to be returned, and of the byte ranges of data to be provided. 

When signing or verifying a PDDoc, the data buffer object is a PDDoc handle and the bytes 

returned will be those defined by /ByteRange in the signature object dictionary. See the PDF 

Reference for details. 

The PSDataBufferDigest uses this method when computing the digest for the data. 

Parameters 

dataBuffer 

maxSize 

pReturnBuffer 

pReturnSize 

The buffer containing the data. 

The maximum number of bytes to return in the return buffer. 

(Filled by the method) A pointer to the buffer containing the 

current bytes to be processed. If NULL, an error occurred and you 

should abort the enumeration. 

(Filled by the method) A pointer to the size in bytes of the return 

buffer. When 0, do not process the return buffer, but continue 

enumerating until the method returns false. Always less than 

maxSize. 

Return Value 

true as long as there is more data to process, false when the end of the buffer is 

reached. 

Header File 

PubSecHFT.h 




2 



PSExportDataExchange 

ASBool PSExportDataExchange 

(PSExportDataExchangeParams params); 

Description 

Exports certificates, requests for certificates, and so on, to FDF files or other file types, using 

a UI wizard interface. Includes support to export to a file or to email. 

The specified type of data is exported to a file and optionally emailed to a destination that 

is chosen using the wizard. 

● If the data is saved to a file and is the user's own contact information, it can be a PKCS#7 

file (.p7c). 

● If the data contains just one certificate and is saved to a file, it can be a raw certificate file 

(.cer). 

● Otherwise, it is always an FDF file. 

Does not raise or throw. Displays an alert if unsuccessful. 

Parameters 

params 

A structure containing the export parameters. 

Return Value 


Header File 

PubSecHFT.h 


PSImportDataExchange 




2 


ASBool PSImportDataExchange 

(PSImportDataExchangeParams params); 

Description 

Imports FDF data from a file, using a UI wizard interface. The parameters structure specifies 

the type and location of the data. This call is used, for example, by the Directory 

configuration dialog to import directory settings from an FDF file. 

When you use this call (rather than opening the FDF file directly) the PubSec FDF handling 

code is used, which provided support for FDF signature verification. PubSec opens the FDF 

file, then calls the handler’s PSImportDataProc, using the handler and engine specified 

in the parameters structure. 

The operation fails if the data is not of the specified type. Does not raise or throw. Displays 

an alert if unsuccessful. 

Parameters 

params 

A structure containing the import parameters. 

Return Value 


Header File 

PubSecHFT.h 




2 



PSRegisterHandler 

ASBool PSRegisterHandler (ExtensionID owner, 

PubSecHandler psHandler); 

Description 

Registers a handler with the PubSec HFT. The caller retains ownership of the 

PubSecHandlerRec. 

Parameters 

owner 

psHandler 

The handler’s plug-in ExtensionID, assigned at initialization. 

The handler structure containing the handler methods to register. 

Return Value 


Header File 

PubSecHFT.h 


PSUnregisterHandler 




2 

PSSigValidatePDDocSigField 

ASBool*PSSigValidatePDDocSigField 

(PSSigPDDocParams docParams); 

Description 

Validates a specified signature field in a PDDoc. For example, you might call this from the 

validate button of a signature properties dialog, or if any information used during 

validation is changed. Does not bring up any UI. 

A return value of true indicates that the validation operation was successfully peformed, 

but does not provide any information about the result of the validation (that is, the 

signature’s validity value). The method does not return validity information, but simply 

updates the DigSig and PubSec validation caches. 

N OTE: 

This method cannot validate a signature whose cache has not been updated or is 

NULL. In this case, use the method DigSigVerifySig. 

Parameters 

docParams 

The validation parameters. 

Return Value 

true if the validation was successfully performed, false otherwise. 

Header File 

PubSecHFT.h 


2 




ASBool PSUnegisterHandler (PubSecHandler psHandler); 

Description 

Unregisters a handler from the PubSec HFT. This does not destroy the handler; the caller 

owns the PubSecHandlerRec. 

Parameters 

psHandler 

The handler to unregister. 

Return Value 


Header File 

PubSecHFT.h 





PubSec Acrobat Address Book Methods 

2 


These methods allow you to manage certificates in the Acrobat Address Book (AAB). 

AABFindCertsByName 

void AABFindCertsByName (const ASUns8* inCertNameData, 

ASInt32 inCertNameSize, ASCab outResults); 

Description 

Does a lookup in the Acrobat Address Book by certificate subject name. Returns all 

certificates that match the name along with trust information associated with them. 

The returned ASCab contains: 

● An entry for each certificate, with a 0-based index followed by the X509 certificate as 

ASN1-encoded binary data 

● An entry with a key Tn containing the associated trust value of each certificate, where n 

corresponds to the certificate’s index key. 

If a trust key is missing, the value should be assumed to be untrusted. For example: 

{ ("0", cert1), ("1", cert2), ("T1", kPSSigTrustAuthenticDocuments) } 

In this case, cert1 is untrusted, cert2 is trusted for authentic documents. 

Parameters 

inCertNameData 

inCertNameSize 

outResults 

The subject name of the certificates to find. Specify a BERencoded 

value of ASN.1 type Name defined in X.509 (RFC 3280). 

The size of the certificate subject name data. 

(Filled by the method) An ASCab containing any certificates found 

by the lookup and their trust information. 

Return Value 


Header File 

PubSecHFT.h 


AABGetCertTrust 

AABGetTrustedCerts 


2 



AABGetCertChain 

ASBool AABGetCertChain (const ASUns8* inX509Cert, 

ASInt32 inX509CertSize, ASCab inTrustedCerts, 

ASCab inUntrustedCerts, ASCab outChain); 

Description 

Finds the certificate chain for the specified certificate in the Acrobat Address Book. 

A certificate ASCab contains an entry for each certificate,with a 0-based index followed by 

the X509 certificate as ASN1-encoded binary data; for example: 

Parameters 

{ ("0", cert1), ("1", cert2), ... } 

inX509Cert 

inX509CertSize 

inTrustedCerts 

inUntrustedCerts 

outChain 

The certificate identifier, as defined in X.509 (RFC 3280). This is 

a generic 8-bit pointer to the certificate data. 

The size in bytes of the X.509 certificate pointed to by 

inX509Cert. 

An ASCab containing the user’s trusted certificates. 

An ASCab containing additional certificates needed to build 

the certificate chain. 

(Filled by the method) An ASCab containing the certificate 

chain. The specified certificate itself is at index 0, followed by 

the chain certificates in issuing order. 

Return Value 


Header File 

PubSecHFT.h 






2 


PSSigTrust AABGetCertTrust (const ASUns8* inX509Cert, 

ASInt32 inX509CertSize, ASCab inCertChain, 

ASCab inHelperCerts); 

Description 

Finds the specified certificate in the Acrobat Address Book and returns the trust level. 

Parameters 

inX509Cert 

inX509CertSize 

inCertChain 

inHelperCerts 

The certificate identifier, as defined in X.509 (RFC 3280). This is a 

generic 8-bit pointer to the certificate data. 

The size in bytes of the X.509 certificate pointed to by 

inX509Cert. 

An ASCab containing the certificate chain for the certificate, 

with the trust level for each certificate. It starts with 

inX509Cert's issuer at index 0 and continues in the issuing 

order. Can be NULL if the chain is not available. 

An ASCab containing an unordered sequence of certificates that 

can be used to build the certificate chain. If inCertChain is 

NULL and inX509Cert is not self-signed, PubSec attempts to 

build a chain of certificates using a default mechanism. 

A certificate ASCab contains an entry for each certificate,with a 

0-based index followed by the X509 certificate as ASN1-encoded 

binary data; for example: 

{ ("0", cert1), ("1", cert2), ... } 

Return Value 

The trust value for the specified certificate, if found. If no certificate is found, returns 

kPSSigTrustUntrusted. To distinguish a certificate that is not found from one whose 

trust level is reported as untrusted, use AABIsCertPresent. 

Header File 

PubSecHFT.h 



AABIsCertPresent 


2 




void AABGetTrustedCerts (PSSigTrust inTrust, 

ASCab outResults); 

Description 

Finds the certificates with a specified level of trust in the Acrobat Address Book. 

Parameters 

inTrust 

outResults 

The level of trust for which to find certificates. A logical OR of 

PSSigTrust bit flags. 

(Filled by the method) An ASCab containing the trusted certificates 

found in the AAB. 

A certificate ASCab contains an entry for each certificate,with a 0- 

based index followed by the X509 certificate as ASN1-encoded 

binary data; for example: 

{ ("0", cert1), ("1", cert2), ... } 

Return Value 


Header File 

PubSecHFT.h 






2 

AABIsCertPresent 

ASBool AABIsCertPresent (const ASUns8* x509, ASInt32 size); 

Description 

Finds the specified certificate in the Acrobat Address Book. Use this method to distinguish a 

certificate that is not found by AABGetCertTrust from one whose trust level is reported 

as untrusted. 

Parameters 

x509 The certificate identifier, as defined in X.509 (RFC 3280). 

size The size of the certificate pointed to by x509. 

Return Value 

true if the certificate is found, false otherwise. 

Header File 

PubSecHFT.h 




2 


Digital Signature Appearance File Methods 


These methods allow a handler to access the built-in APIcon appearance handler, through 

the DSAP file. This information is used to display a selection list of signature appearances. 

DSAPFileAcquire 

ASBool DSAPFileAcquire (const ASBool bResolveProblems, 

const ASBool bCreate 

Description 

Acquires the DSAP file and opens it, if it has not already been acquired. 

PubSec calls this method to access a file, so a handler does not need to acquire a DSAP file 

unless it needs to access it for other reasons. 

Parameters 

bResolveProblems 

bCreate 

When true, if there are problems trying to open the file, 

PubSec opens a UI that gives a user the option to delete the 

corrupted file. 

When true, if the file does not exist it is created. Normally 

true. 

Return Value 

true if the file was acquired and opened, false otherwise. 

Header File 

PubSecHFT.h 


DSAPFileRelease 




2 

DSAPFileCanDeleteNthEntry 

ASBool DSAPFileCanDeleteNthEntry (const ASInt32 index); 

Description 

Tests whether a signature appearance entry at a specified index in the DSAP file can be 

edited or is read-only. 

Parameters 

index 

The position of the entry to test. The first entry is at index 0. A negative value 

gets the default entry. 

Return Value 

true if the entry is editable, false otherwise. 

Header File 

PubSecHFT.h 


DSAPFileGetCount 

DSAPFileRemoveNthEntry 


2 



DSAPFileCopyNthEntry 

ASBool DSAPFileCopyNthEntry (const ASInt32 index); 

Description 

Creates a copy of the specified entry in the default DSAP file and appends the copy to the 

end of the list of signature appearances in the file. 

When you copy a default appearance entry, the copy is not considered a default 

appearance entry. 

Parameters 

index 

The position of the entry to copy. The first entry is at index 0. A negative value 

gets the default entry. 

Return Value 

true if the copy was successful and the appearance file was successfully edited and saved, 


Header File 

PubSecHFT.h 



DSAPFileEditNthEntry 




2 


ASBool DSAPFileEditNthEntry (const APPreview previewData, 

const ASInt32 index); 

Description 

Opens the UI that allows the user to edit the specified signature appearance entry of the 

DSAP file. 

Parameters 

previewData 

index 

Data with which to create a signature preview in the edit dialog. 

The position of the entry to edit. The first entry is at index 0. A 

negative value gets the default entry. An index larger than the 

current number of entries creates a new entry. 

Return Value 

true if successful (the changes to the entry were made and saved), false otherwise. 

Header File 

PubSecHFT.h 



DSAPFileCopyNthEntry 


2 




ASInt32 DSAPFileGetCount (void) 

Description 

Gets the number of configured signature appearance entries in the DSAP file, 

Parameters 

None 

Return Value 

The number of configured AP entries. 

Header File 

PubSecHFT.h 






2 

DSAPFileGetNewNthName 

ASText DSAPFileGetNewNthName (const ASInt32 index); 

Description 

Gets a copy of the name of the specified signature appearance entry in the DSAP file. Use 

this when building a list of signatures for a user to choose from or edit. 

Parameters 

index 

The position of the entry whose name to obtain. The first entry is at index 0. A 

negative value gets the default entry. 

Return Value 

A copy of the name as an ASText object. 

Header File 

PubSecHFT.h 




2 




void DSAPFileRelease (void); 

Description 

Closes the digital signature appearance (DSAP) file. 

Parameters 

None 

Return Value 

None 

Header File 

PubSecHFT.h 



DSAPFileSave 




2 

DSAPFileRemoveNthEntry 

ASBool DSAPFileRemoveNthEntry (const ASInt32 index); 

Description 

Deletes the specified signature appearance entry from the DSAP file. 

Parameters 

index 

The position of the entry to remove. The first entry is at index 0. A negative 

value gets the default entry. 

Return Value 


Header File 

PubSecHFT.h 





2 



DSAPFileSave 

void DSAPFileSave (void); 

Description 

Saves the DSAP file if it is dirty, leaving it open. 

Parameters 

None 

Return Value 

None 

Header File 

PubSecHFT.h 






2 


2 




3 

PubSec Callbacks 

PSDestroyEngineProc 

ACCB1 void (ACCB2 *PSDestroyEngineProc) 

(PubSecEngine engine); 

Description 

Destroys a public key security engine for this handler, freeing the memory. 

Parameters 

engine 

The engine to be destroyed. 

Return Value 

None 

Header File 

PubSecHFT.h 


PSNewEngineProc 


3 


PSExportDataProc 

ACCB1 DSRetCode (ACCB2 *PSExportDataProc) 

(PubSecEngine engine, PSExportDataType dataType, 

ASCab outCab, ASBool bInUIAllowed); 

Description 

This function gets data of the specified type from a handler, to be exported to an FDF or 

CMS file and possibly sent as an email attachment. The function is called when exporting 

to FDF, for example, in response to an FDF Data Exchange certificate request. 

Acrobat calls PSGetBoolPropertyProc to see if the relevant data type is supported in 

the handler implementation. See PSExportDataType. 

Parameters 

engine 

dataType 

outCab 

bInUIAllowed 

The engine for which the data is exported. 

The type of data to be exported. 

The ASCab containing the data to be exported. 

When true, the call can invoke the UI to export the data. 

Return Value 

Positive on success. 

Header File 

PubSecHFT.h 


PSImportDataProc 



3 

PSGetAtomPropertyProc 

ACCB1 ASAtom (ACCB2 *PSGetAtomPropertyProc) 

(PubSecEngine engine, const char* szPropertyName); 

Description 

Gets an ASAtom property of an engine. (For a list of public properties of a 

PubSecEngine, see PubSecHFT.h.) 

Parameters 

engine 

szPropertyName 

The engine for which the property value is obtained. 

The name of the ASAtom property whose value is obtained. 

Return Value 

The ASAtom property value, or ASAtomNull if the property value is not set. 

Header File 

PubSecHFT.h 


PSGetBoolPropertyProc 

PSGetInt32PropertyProc 

PSGetTextPropertyProc 


3 



ACCB1 ASBool (ACCB2 *PSGetBoolPropertyProc) 

(PubSecEngine engine, const char* szPropertyName, 

const ASBool defaultValue); 

Description 

Gets an ASBool property of an engine. (For a list of public properties of a 


Parameters 

engine 


defaultValue 


The name of the ASBool property whose value is obtained. 

The value to return if the property value is not set. 

Return Value 

The boolean property value, or the specified default value if the property value is not set. 

Header File 

PubSecHFT.h 







3 

PSGetDirHandlerInfo 

ACCB1 DSRetCode (ACCB2 *PSGetDirHandlerInfo) 

(PubSecEngine engine, DirHandlerInfo outDirHandlerInfo); 

Description 

Gets information about directory handlers in an engine that is acting as a directory service 

provider. 

Parameters 

engine 

outDirHandlerInfo 

The engine for which the information is obtained. 

(Filled by the method) A structure containing an array of 

ASCab directory handlers. 

Return Value 


Header File 

PubSecHFT.h 


PSGetDirInfo 

PSGetDirList 

PSOpenConnection 

PSSetDirInfo 


3 


PSGetDirInfo 

ACCB1 DSRetCode (ACCB2 *PSGetDirInfo) 

(PubSecEngine engine, ASAtom inDirID, 

DirectoryInfo outDirInfo); 

Description 

Gets information about directories in an engine that is acting as a directory service 

provider. 

Parameters 

engine 

inDirID 

outDirInfo 


The unique identifier associated with the directory. See 

DirHandlerInfo. 

(Filled by the method) An ASCab containing information about the 

directory. 

Return Value 


Header File 

PubSecHFT.h 



PSGetDirList 


PSSetDirInfo 



3 

PSGetDirList 

ACCB1 DSRetCode (ACCB2 *PSGetDirList) 

(PubSecEngine engine, DirectoryList outDirList); 

Description 

Gets a list of directories in an engine that is acting as a directory service provider. 

Parameters 

engine 

outDirList 


(Filled by the method) An ASCab containing an array of 

DirectoryInfo ASCab objects. 

Return Value 


Header File 

PubSecHFT.h 



PSGetDirInfo 


PSSetDirInfo 


3 


PSGetImplicitRecipientsProc 

ACCB1 DSRetCode (ACCB2 *PSGetDirHandlerInfo) 

(PubSecEngine engine, DirHandlerInfo outDirHandlerInfo); 

Description 

Gets information about directory handlers in an engine that is acting as a directory service 

provider. 

Parameters 

engine 

outDirHandlerInfo 


(Filled by the method) An ASCab containing an array of 

ASCab directory handlers. 

Return Value 


Header File 

PubSecHFT.h 


PSGetDirInfo 

PSGetDirList 

PSSetDirInfo 



3 


ACCB1 ASInt32 (ACCB2 *PSGetInt32PropertyProc) 


const ASInt32 defaultValue); 

Description 

Gets an ASInt32 property of an engine. (For a list of public properties of a 


Parameters 

engine 


defaultValue 


The name of the ASInt32 property whose value is obtained. 

The value to return if the property value is not set. 

Return Value 

The ASInt32 property value, or the specified default value if the property value is not set. 

Header File 

PubSecHFT.h 






3 


PSGetLogoProc 

ACCB1 void (ACCBPROTO2 *PSGetLogoProc) 

(ASAtom label, const char* *pcLogo, 

const ASFixedRect* *pRect); 

Description 

Gets custom artwork from the handler, to be used as a label for a particular validity state. 

The artwork for standard labels does not need to be specifically retrieved. If you are not 

using dynamic signature appearances or not using custom artwork, the handler need only 

handle the null-label case. 

Parameters 

label 

pcLogo 

pRect 

A validity state, as returned by PSSigValGetAPLabelProc, for 

which to use this logo. If ASAtomNull, the logo is used as an 

invariable watermark of the signature appearance. 

(Filled by the method) A string of the uncompressed graphics stream 

for the logo artwork. 

(Filled by the method) The precise bounding box that the artwork 

occupies. 

Return Value 

None 

Header File 

PubSecHFT.h 


PSSigCreateAPNXObjProc 

PSSigValGetAPLabelProc 



3 


ACCB1 ASText (ACCB2 *PSGetTextPropertyProc) 


const ASInt32 index); 

Description 

Gets an ASText property of an engine. (For a list of public properties of a 


For the PROP_PSENG_Exception property, index is a DSRetCode value. If a handler 

receives a a call to get PROP_PSENG_Exception, it must reset its exception status so 

that subsequent calls to get an exception string return NULL. 

NULL return values are legal for all properties. 

Parameters 

engine 


index 


The name of the ASText property whose value is obtained. 

The index of the string to obtain if the property contains a list of 

values. If it does not, index is ignored. 

Return Value 

The ASText property value, or NULL if the property value is not set. 

Header File 

PubSecHFT.h 






3 



ACCB1 DSRetCode (ACCB2 *PSImportDataProc) 

(PubSecEngine engine, PSImportDataParams params, 

ASBool bInUIAllowed); 

Description 

This function sends data of a particular type to a handler to import into its own data store. 

This is call is executed in response to data received, for example, through an FDF file or 

through the signature dictionary. 

Acrobat calls PSGetBoolPropertyProc to see if the relevant data type is supported in 

the handler implementation. See PSImportDataType. 

Parameters 

engine 

params 

bInUIAllowed 


A structure that contains the data to be imported. 

When true, the call can invoke the user-interface dialogs if needed. 

Return Value 


Header File 

PubSecHFT.h 





3 

PSNewEngineProc 

ACCB1 PubSecEngine (ACCB2 *PSNewEngineProc) ( ); 

Description 

Creates a new public key security engine for this handler, not associated with any UI. 

Parameters 

None. 

Return Value 

The new engine. 

Header File 

PubSecHFT.h 


PSDestroyEngineProc 


3 


PSOpenCMSEnvelopeProc 

ACCB1 DSRetCode (ACCB2 *PSOpenCMSEnvelopeProc) 

(PubSecEngine engine, PSOpenCMSEnvelopeParams params, 

ASBool bInUIAllowed ); 

Description 

This procedure is required. Called to open the provided PKCS#7 cryptographic message 

service (CMS) enveloped data object and return the data contained in it. 

Parameters 

engine 

params 

bInUIAllowed 


A structure containing the envelope data and fields for the 

handler to return opened envelope data contents, and 

optionally the session key and opening certificate. 

When true, the call can invoke the UI for anything required 

to open the envelope. For instance, a login may be needed 

to access the user's private key. 

Return Value 

kDSTrue if the envelope was opened, kDSFalse if the envelope could not be opened, or 

an error code in case of error. 

Header File 

PubSecHFT.h 



3 


ACCBPROTO1 DSRetCode (ACCBPROTO2 *PSOpenConnection) 

(PubSecEngine engine, ASAtom inDirID, 

DirAuthenticationContext inAuthCtx, ASBool inUI, 

DirConnection* pOutConnection); 

Description 

Opens a connection to a specified directory to use for authentication. 

Parameters 

engine 

inDirID 

inAuthCtx 

inUI 

pOutConnection 

The engine for which the connection is opened. 

The identifier for the directory to which the connection is opened. 

Not currently supported. Pass as NULL. 

Whether the authentication UI should be shown. 

(Filled by the method) A pointer to the new connection object. 

Return Value 

kDSTrue if the connection is opened, or kDSFalse if it is not. 

Header File 

PubSecHFT.h 

Related Callbacks 


PSGetDirInfo 

PSGetDirList 

PSSetDirInfo 


3 


PSPerformOperationProc 

ACCB1 DSRetCode (ACCB2 *PSPerformOperationProc) 

(PubSecEngine engine, PSPerformOpType type, 

const ASCab cab, ASBool bUI); 

Description 

Performs the specified operation using parameters contained in cab. This interface is used 

by EScript. 

Parameters 

engine 

type 

cab 

bUI 

The engine for which the operation is performed. 

The type of operation to perform. 

An ASCab containing parameters for the requested operation, or 

NULL to test whether the operation is supported. 


Return Value 

If cab is NULL, returns kDSTrue if the operation is supported, or kDSFalse if it is not. 

If cab contains data, returns kDSOk if the operation is successful, an exception code if not. 

Header File 

PubSecHFT.h 



3 

PSSessionAcquireProc 

ACCB1 DSRetCode (ACCB2 *PSSessionAcquireProc) 

(PubSecEngine engine, PDDoc pdDoc, PSSessionOpType opType, 

ASText opText, ASCab cabParams, ASBool bUIAllowed); 

Description 

Called to acquire resources that will be needed to begin a PubSec session. For example, it 

might need to log on before performing a desired operation. If resources are already 

available, the handler may not need to do anything. 

When the function completes successfully, PubSec calls PSSessionReleaseProc with 

the same operation type. Multiple calls can be made to acquire the same or different 

operation types, before a previously acquired resource is released. Handlers should keep a 

reference count if required for a particular resource. 

Despite the name, this function does not acquire a session, just the resources that will be 

needed by the session. For example, to begin a signing session, PubSec calls 

PSSessionAcquire with kPSOpTypePDDocSign. The PubSec handler should select 

the resources and credentials that are to be used for signing. If the call is successfull, PubSec 

will proceed with the PSSigGetSigPropertiesProc and 

PSSigGetSigValueProc calls. 

Parameters 

engine 

pdDoc 

opType 

opText 

cabParams 

bUIAllowed 


The PDF document for which the session is acquired. 

The operation that is the reason for acquiring the session. 

A human-readable version of the reason for acquiring the session. If 

not supplied, opType is used to build text. 

An ASCab object containing information about the acquisition, 

owned by PubSec. Currently not used, passed as NULL. 


Return Value 


Header File 

PubSecHFT.h 


PSSessionReadyProc 

PSSessionReleaseProc 


3 



ACCB1 DSRetCode (ACCB2 *PSSessionReadyProc) 

(PubSecEngine engine, PSSessionOpType opType); 

Description 

Returns kDSTrue if the resources and information needed to perform the specified 

operation have been acquired. 

Parameters 

engine 

opType 


The operation for which the session is needed. 

Return Value 

kDSTrue if the session is ready, otherwise kDSFalse. 

Header File 

PubSecHFT.h 






3 


ACCB1 DSRetCode (ACCB2 *PSSessionReleaseProc) 

(PubSecEngine engine, PSSessionOpType opType); 

Description 

Releases any resources that were required for the specified operation, such as file handles. 

It is up to a handler to decide what resources to release. A handler can, for example, leave a 

user logged on, even after a session is released. 

This call can fail. For example, you might want the call to fail if the operation is 

kPSOpTypeEScriptLogin and encrypted documents are open. 

Parameters 

engine 

opType 

The engine for which the session was acquired. 

The operation for which the session was needed. 

Return Value 

kDSTrue if the session is successfully released, otherwise kDSFalse. 

Header File 

PubSecHFT.h 





3 


PSSetDirInfo 

ACCB1 DSRetCode (ACCB2 *PSSetDirInfo) 

(PubSecEngine engine, DirectoryInfo inDirInfo); 

Description 

Sets information about a directory in an engine that is acting as a directory service provider. 

Parameters 

engine 

inDirInfo 


An ASCab containing information about the directory. 

● If the PROP_DirectoryInfo_ID value matches one of the 

existing directories, that directory's information is overwritten. 

● If it does not match any existing directory, a new directory is 

created. 

Return Value 

kDSOk if successful, otherwise an exception code. 

Header File 

PubSecHFT.h 



PSGetDirInfo 

PSGetDirList 




3 

PSSigAuthenticateProc 

ACCB1 DSRetCode (ACCB2 *PSSigAuthenticateProc) 

(PubSecEngine engine, const PDDoc pdDoc, ASCab inESParams, 

ASBool bInUIAllowed); 

Description 

Called to authenticate the signer. The caller can determine whether authentication is 

required by calling PSGetBoolPropertyProc with the property 

PROP_PSENG_IsAuthenticated. 

This procedure is called only if specified by the PSSigSigPropParams passed to 

PSSigGetSigPropertiesProc. If your handler does not need this call, it should be 

defined to always return kDSTrue. 

Parameters 

engine 

pdDoc 

inESparams 

bInUIAllowed 

The engine for which signature authentication is performed. 

A PDF document for window parenting. NULL if there is no PDDoc. 

Optional. An ASCab containing authentication parameters. If not 

supplied or if authentication fails, and if bInUIAllowed is true, 

brings up the authentication UI to obtain parameters. 

When true, the call can invoke the authentication UI. 

Return Value 

kDSTrue if authentication succeeds, kDSFalse if authentication fails. 

Header File 

PubSecHFT.h 



PSSigGetSigValueProc 

PSSigValidateProc 


3 



ACCB1 DSRetCode (ACCB2 *PSSigCreateAPNXObjProc) 

(PubSecEngine engine, CosObj *pOutXObj, 

PSSigPDDocParams docParams, PSAPSigType sigType); 

Description 

Creates the signature appearance that is put into the /AP dictionary /N entry. 

It is recommended that you set this procedure to NULL, w hich allows PubSec to use the 

default APHandler to generate the XObj for the appearance. 

Parameters 

engine 

pOutXObj 

docParams 

sigType 

The engine for which an appearance is created. 

(Filled by the method) The XObject to use for the signature appearance. 

A validation parameters structure containing information that is 

needed to create the signature appearance, such as the PDDoc and 

annotation. 

The signature type. 

Return Value 


Header File 

PubSecHFT.h 


PSGetLogoProc 




3 

PSSigGetSigPropertiesProc 

ACCB1 DSRetCode (ACCB2 *PSSigGetSigPropertiesProc) 

(PubSecEngine engine, PSSigSigPropParams params); 

Description 

Called when creating a new signature. For PDDoc signatures, this call replaces SigNew 

and SigCommit calls. It returns the values that PubSec writes into the signature dictionary 

in the parameters structure. 

Before making this call, the handler should use PSSessionAcquireProc to choose the 

credential to be used for signing. 

The handler can use the UI during this call to allow authentication and to bring up the 

signing dialog. 

Parameters 

engine 

params 

The engine for which signature properties are retrieved. 

A signature properties parameters structure. 

Return Value 


Header File 

PubSecHFT.h 


PSGetLogoProc 





3 



ACCB1 DSRetCode (ACCB2 *PSSigGetSigValueProc) 

(PubSecEngine engine, 

PSSigGetSigValueParams inOutParams); 

Description 

Called to sign the digest and return the signature value. The memory for the signature 

value becomes the property of the caller. 

When called for a PKCS #7 signature, there is a "size-only" option: if the value of 

pOutSigValueData in the inOutParams structure is NULL, returns the expected size 

of the signature value. 

For most values of digestMethod in the inOutParams structure, the digest is passed 

into the handler, and the handler needs to sign it. However if a handler specifies that it must 

do its own digest ( for example, for the legacy EntrustFile toolkit) then a NULL digest is 

passed in. The handler can specify this using 

PROP_PSENG_SignFormatPKCS7Digest. If and only if this property is true, the digest 

is not passed to the handler. 

This procedure should not show any user interface and not allow a user to cancel the 

signing operation. 

Parameters 

engine 

params 

The engine for which a signature value is created. 

(Modified by the method) A structure containing signature-value 

parameters and return values. 

Return Value 


Header File 

PubSecHFT.h 







3 

PSSigPropDialogProc 

ACCB1 DSRetCode (ACCB2 *PSSigPropDialogProc) 


PSSigValidateDialogParams valParams); 

Description 

Called to show a dialog that shows signature properties. 

If this procedure is NULL (which is recommended), PubSec opens its own properties dialog. 

The default properties dialog includes buttons that allow the user to import and to display 

certificates: 

● The import button calls PSImportDataProc. 

● If the handler implements the kPSOpPerformDisplayCertList operation (see 

PSPerformOperationProc) the show-certificate button can open the handlerprovided 

display dialog. Otherwise, the button opens the default certificate-display 

dialog. 

Parameters 

engine 

valParams 

The engine for which the validation status is shown. 

(Modified by the method) A properties-dialog parameters and return 

values structure. The handler can set the dsPropType to 

kSDPropViewVersion to request rollback to this signature when 

the dialog is closed. 

Return Value 


Header File 

PubSecHFT.h 


PSSigValidateDialogProc 


3 



ACCB1 ASAtom (ACCB2 *PSSigValGetAPLabelProc) 

(ASCab valCab, const ASInt32 layerNum); 

Description 

Called to get a name to use for a particular layer of signature appearance. This is used when 

the signature appearance uses the n1 and n3 layers for dynamic signature appearances. 

Beginning in Acrobat 6.0, Acrobat is discouraging the use of dynamic signature 

appearances and is instead showing the signature validity as an icon that is rendered at run 

time. 

Provide this prededure for handlers that need to be backward compatible with earlier 

implementations that use custom artwork. The procedure can be set to NULL when not 

using dynamic signature appearances. 

If the value DSAPValid, DSAPDoubleValid, or DSAPInvalid is returned, Acrobat 

uses standard labels. Otherwise Acrobat calls PSGetLogoProc to return logo artwork to 

use for the XObject. A return value of ASAtomNull causes Acrobat to use a blank XObject 

for the specified layer. 

Parameters 

valCab 

layerNum 

An ASCab containing the signature validation result for which the 

label is obtained. 

The layer for which a label is obtained. 

Return Value 

The label of a signature appearance layer as an ASAtom. 

Header File 

PubSecHFT.h 


PSGetLogoProc 




3 

PSSigValGetTextProc 

ACCB1 ASText (ACCB2 *PSSigValGetTextProc) 

(ASCab valCab, const DSSigValText textType, 

const ASInt32 index ); 

Description 

Called to get the text result of validation. For most values of textType, the handler should 

return NULL, causing PubSec to use the default text strings ("Valid," "Invalid," or "Unknown," 

depending on the validity state). Handlers will normally need to provide their own ID 

validity strings. 

Parameters 

valCab 

textType 

index 

The ASCab containing the validation result. (See 

PSSigValidateParams.) 

The type of result text to obtain, for a specific context. 

If the type is kDSSigValTextAP, the corresponding index value. 

Otherwise ignored. 

Return Value 

The text result of validation as a new ASText object. 

Header File 

PubSecHFT.h 





3 



ACCB1 DSRetCode (ACCB2 *PSSigValidateDialogProc) 


PSSigValidateDialogParams valParams); 

Description 

Called to show a dialog that shows validation status, after the signature is validated. 

If this procedure is NULL (which is recommended), PubSec opens its own validation dialog. 

Parameters 

engine 

valParams 

The engine for which the validation status is shown. 

A validation dialog parameters structure. The validation state 

resulting from the previous validation operation is passed in the 

sigValCab field. 

The handler can update the dsPropType field if the properties 

dialog should be opened next. 

Return Value 


Header File 

PubSecHFT.h 




PSSigPropDialogProc 


PSSigValidateSupportedProc 



3 


ACCB1 DSRetCode (ACCB2 *PSSigValidateProc) 

(PubSecEngine engine, PSSigValidateParams params ) 

Description 

Called to validate a signature. 

Parameters 

engine 

params 

The engine for which the signature is validated. 

(Modified by the method) A signature validation parameters and return 

values structure. The result of validation is stored in the sigValCab 

field. 

Return Value 


Header File 

PubSecHFT.h 







3 



ACCB1 PSSigValSupport (ACCB2 *PSSigValidateSupportedProc) 

(PubSecEngine engine, PSSigValidateSupportParams params ) 

Description 

Called to determine whether the handler can validate a signature. 

Parameters 

engine 

params 

The engine for which the signature is validated. 

A parameters structure containing information about the signature to 

be validated. 

Return Value 

A signature-validation support value. 

Header File 

PubSecHFT.h 







4 

PubSec Declarations 

These data structures and declarations are used by the PubSec methods. 

APPreview 

typedef struct _t_APPreviewRec { 

const char* logo; 

ASFixedRect* logoBBox; 

ASText fName; 

ASText fDN; 

ASText fReason; 

ASText fLocation; 

ASFixed fWidth; 

ASFixed fHeight; 

bool fbAuthSig; 

} APPreviewRec, *APPreview; 

Description 

Data with which to build a signature preview in the edit dialog for a signature appearance 

file entry. 

Members 

logo 

logoBBox 

fName 

fDN 

fReason 

fLocation 

fWidth 

fHeight 

fbAuthSig 

The logo string. 

The bounding box for the logo string. 

The entry name. 

The distinguished name. 

The reason for signing. 

The location of signing. 

The width and height that determine the aspect ratio of the preview 

image. 

true if this is an author signature, false otherwise. 


4 


Header File 

PubSecHFT.h 





4 

DirAuthenticationContext 

typedef ASCab DirAuthenticationContext; 

Description 

An ASCab object containing authentication details such as the user name and password. It 

could be used to override the default authentication entries, or to avoid repeated 

authentications in case the context could be cached. The actual contents depend on the 

directory handlers. The currently supported directory handlers (AAB and LDAP) do not 

support this feature. 

Header File 

PubSecHFT.h 




4 


DirConnection 

typedef struct _t_DirConnection* DirConnection; 

Description 

A directory connection object, defined in the Acrobat Directory Services. 

Header File 

DirectoryHFT.h 





4 

DirectoryInfo 

typedef ASCab DirectoryInfo; 

Description 

A directory information ASCab that contains a UI name as an ASText and a unique id as 

an ASAtom. 

A directory information structure contains configuration settings used to establish a 

connection to a directory, including a UI name and unique identifier. It contains standard 

entries that use the prefix dirStdEntry, and can also contain other configuration 

information specific to a directory. 

Common top-level properties are: 

Property Type Description 

dirStdEntryName ASText (Required) Name of this directory 

for display; for example, "Adobe 

Employees". 

dirStdEntryID ASAtom (Required) Unique identifier for 

the directory. For example: 

Adobe.PPKMS.LDAP.dir0. 

dirStdEntryPrefDirHandlerID ASAtom (Optional) Languageindependent 

name of the 

directory handler to be used 

when connecting to this 

directory; for example, 

Adobe.PPKMS.ADSI. 

Required when there are multiple 

directory handlers within a DSP. 

dirStdEntryDirType ASAtom (Optional) Languageindependent 

name for the type 

of the directory; for example, 

LDAP. 

Required when entries are to be 

imported or exported. 


4 


Header File 

Property Type Description 

dirStdEntryVersion ASInt32 (Optional) The version of the 

directory. It is currently 

0x00010000 for all the directory 

types currently supported(ADSI, 

AAB), indicating that this is the 

first revision of that structure. The 

version number will be 

incremented as the structure 

changes. 

DirectoryHFT.h 


PSGetDirInfo 




4 

DirectoryList 

typedef ASCab DirectoryList; 

Description 

A directory information list ASCab contains a vector of nested DirectoryInfo ASCabs, 

one for every directory contained within the engine. Each directory ASCab contains a UI 

name as an ASText and a unique id as an ASAtom. 

Header File 

PubSecHFT.h 


PSGetDirList 


4 


DirectoryInfo 

typedef ASCab DirHandlerInfo; 

Description 

A directory handler information ASCab contains a vector of nested ASCabs, one for every 

directory handler contained within the engine. Each directory handler ASCab contains a UI 

name and a unique identifier; for example, Adobe.PPKMS.LDAP. The key names for the 

properties are: 

PROP_DirHandlerInfo_Name ASText Required. UI name for the handler. 

PROP_DirHandlerInfo_ID ASAtom Required. Unique identifier for the 

directory handler. The handler is 

rejected if the ASAtom conflicts with 

one already registered. 

Header File 

PubSecHFT.h 





4 

DirHandlerInfo 

typedef ASCab DirHandlerInfo; 

Description 

A directory handler information ASCab contains a vector of nested ASCabs, one for every 

directory handler contained within the engine. Each directory handler ASCab contains a UI 

name and a unique id; for example, "Adobe.PPKMS.LDAP". The key names for the properties 

are: 

PROP_DirHandlerInfo_Name ASText Required. UI name for the handler. 

PROP_DirHandlerInfo_ID ASAtom Required. Unique identifier for the 

directory handler. The handler is 

rejected if the ASAtom conflicts with 

one already registered. 

Header File 

PubSecHFT.h 




4 


DSAPFile 

typedef struct CAPIconFile *DSAPFile; 

Description 

A signature appearance file object to be used by handlers to access the built-in APIcon 

appearance handler. 

Header File 

PubSecHFT.h 





4 

DSDigestMethod 

typedef enum { 

kDSDigestNone=0, 

kDSDigestMD5, 

kDSDigestSHA1, 

kDSDigestEnumSize 

} DSDigestMethod; 

Description 

Constants that specify the method to use for creating a signature digest. 

Header File 

DigSigHFT.h 




4 


DSPropertyType 


kDSPropNone=0, 

kDSPropSignature, 

kDSPropLegal, 

kDSPropViewVersion, 

kDSPropTypeEnumSize 

} DSPropertyType; 

Description 

Constants that specify what dialog to show. 

Values 

kDSPropNone 

kDSPropSignature 

kDSPropLegal 

kDSPropViewVersion 

Do not show signature properties dialog. 

Show general signature properties dialog. 

Show legal notice dialog. 

Show signature rollback (will actually rollback to this 

signature). 

Header File 

DigSigHFT.h 

Related Structures 

PSSigValidateDialogParams 





4 

DSRetCode 

typedef ASInt32 DSRetCode; 

Description 

A return value code for PubSec callback methods. All negative return values are considered 

exceptions. 

Values 

kDSException (-2) 

kDSParameterError (-1) 

kDSFalse (0) 

kDSTrue (1) 

kDSOk (1) 

Get exception string. When this is returned, 

exception text should be available from the called 

routine. If the exception text is NULL, it is 

considered to be an unknown error. 

Error in a parameter to the function call. No 

exception string. 

A boolean return value. 

Success. 

Header File 

DigSigHFT.h 


numerous 


4 


DSSaveType 


DSSignCancel=0, 

DSSignSave, 

DSSignSaveAs, 

DSSaveTypeEnumSize 

} DSSaveType; 

Description 

A return type for DigSig and PubSec callback. 

Values 

DSSignCancel 

DSSignSave 

DSSignSaveAs 

Do not proceed with signing. 

Save over old file. 

Save to new file. 

Header File 

DigSigHFT.h 



DSNewSigDataWithParamsProc 



4 

DSSigValText 


kDSSigValTextNull, 

kDSSigValTextDSTop, 

kDSSigValTextDSDetail, 

kDSSigValTextDSTooltip, 

kDSSigValTextSigInfo, 

kDSSigValTextVal, 

kDSSigValTextProp, 

kDSSigValTextAP, 

kDSSigValTextPropIdValidity, 

kDSSigValTextDSAVIdValidity, 

kDSSigValTextDSTTIdValidity, 

kDSSigValTextEnumSize 

} DSSigValText; 

Description 

Types of text requested by PSSigValGetTextProc for a signature-validity ASCab 

object. The strings are generated by the handler, usually on the fly, when requested. A 

handler can cache the values in the sigVal ASCab (Acrobat plug-ins do not do this). 

PubSec copies values for DSTop, DSDetail, DSDetails and DSTooltip to the 

signature-propeties ASCab. 

● For optional entries, returning NULL causes PubSec to generate the values. 

● Depending on the context, one of the *IdValidity entries is required to specify the 

signer identity validity. 

Values 

kDSSigValTextNull 

kDSSigValTextDSTop 

kDSSigValTextDSDetail 

kDSSigValTextDSTooltip 

kDSSigValTextSigInfo 

kDSSigValTextVal 

Never called, should return NULL. 

Optional. Get text to show in AVPanel, 

added to end of signature summary line. 

Optional. Get text to show in AVPanel, 

shown in signature detail title line. 

Optional. Get text to show in tooltip when 

mouse is over signature annotation. 

Optional. Get text to show in EScript 

SignatureInfo object. 

Optional. Get text to show in validate alert 

dialog. 


4 


kDSSigValTextProp 

kDSSigValTextAP 

kDSSigValTextPropIdValidity 

kDSSigValTextDSAVIdValidity 

kDSSigValTextDSTTIdValidity 

Optional. Get text to show in signature 

properties dialog. 

Optional. Get text to show in appearance, if 

signature appearance uses layer n4 (not 

recommended). In this case, you must also 

pass an index. 

Get text to describe validity of the signer 

certificate (used in properties and validity 

dialogs). 


certificate (used in AVPanel). 


certificate (appended to tooltip, called only 

when describing why certificate is invalid). 

Header File 

PubSecHFT.h 


PSSigValGetTextProc 



4 

PSAPSigType 


kPSAPSigPreExists=0, 

kPSAPSigTentative, 

kPSAPSigPreview 

} PSAPSigType; 

Description 

A signature type to use for generating a signature appearance. 

Values 

kPSAPSigPreExists 

kPSAPSigTentative 

kPSAPSigPreview 

Signing a pre-existing signature field. 

Creating a signature on the fly on a page. 

Creating a preview of a signature. 

Header File 

PubSecHFT.h 




4 


PSDataBuffer 

typedef struct _s_PSDataBufferRec PSDataBufferRec, 

*PSDataBuffer; 

Description 

A buffer of data to be hashed when signing or verifying signatures. The buffer contains the 

bytes to be signed (by ByteRange) when signing a PDF file. 

Header File 

PubSecHFT.h 






4 

PSExportDataExchangeParams 

typedef struct _t_PSExportDataExchangeParamsRec { 

ASSize_t size; 

PubSecHandler psHandler; 

PubSecEngine psEngine; 

PSExportDataType dataType; 

ASCab dataCab; 

PSExportDataType requestType; 

PSExportDestType destType; 

} PSExportDataExchangeParamsRec, *PSExportDataExchangeParams; 

Description 

Parameters for exporting data from PubSec to a file. 

Members 

size 

psHandler 

psEngine 

dataType 

dataCab 

requestType 

The size of the structure. 

If exporting FDF, the handler to use to sign the FDF. If not supplied, 

the user is prompted for a handler 

If exporting FDF, the engine to use to sign the FDF. If not supplied, the 

method uses the default (UI) engine. 

Type of data to be exported. One of: 

● kPSExportDataNone: Not specified. 

● kPSExportDataMyContact: Export the user's own contact 

information (certificates for encryption and/or signing). 

● kPSExportDataContacts: Export a list of contacts from an 

address book or directory that are to be shared. 

● kPSExportDataDirSettings : Export list of directory 

settings that can be used to help someone else configure their 

directory. 

Required. Data to export, or an empty ASCab if there is no data to 

export. Format defined below. 

The type of data to be requested. If supplied, the method adds a 

request to the FDF for this data type and forces the export format to 

be FDF. Same possible values as dataType. 


4 


destType 

The destination type that specifies how data should be delivered. 

One of: 

● kPSExportDestNone: Not specified, prompt the user 

(recommended) 

● kPSExportDestFile: Save as unspecified file type, possibly 

prompting for the file type. 

● kPSExportDestCMSFile: Save as CMS file. 

● kPSExportDestFDFFile: Save as FDF file. 

● kPSExportDestEMailFDF: Save a email FDF file. 

● kPSExportDestCertURL: Send single certificate to URL. 

The dataCab Format 

A top level ASCab contains lists of PROP_ExportDataCab_Contacts, 

PROP_ExportDataCab_DirSettings or whatever other data is to be included. This 

top level cab can include entries for an EMail address (used as the return email address) and 

cn. It is recommended that the cn entry be set to the common name of the user; this will be 

used only in creating the filename for the FDF (or PKCS#7) file. If either of cn or EMail 

address are not provided they are fetched from the AVIdentity preference settings. 

Contents of the individual list entries are added as CosDicts to the FDF file after adding a 

/Type attribute and changing /Certs entries into /CMS entries (because the FDF format 

supports only CMS). Refer to the FDF Data Exchange specification for details of attributes. 

● Each contact can include an email address and a list of certificates (as /Certs entries or as 

CMS objects). 

● Each directory entry contains directory-specific information that can be converted to a 

CosDict before storing in the FDF file. File entries give cDIPaths to files that are to 

be embedded. 

Example cab for exporting a contact: 

dataCab : Cab 

"Contacts" : Cab 

"0" : Cab 

"EMail" : "jsmith@smithcorp.com" 

"Certs" : Cab 

"0" : binary end entity cert 

"cn" : "John Smith" 

"EMail" : "jsmith@smithcorp.com" 

Example cab for exporting directory settings: 

dataCab : Cab 

"DirSettings" : Cab 

"0" : Cab 

"Port" : 369 

Header File 

PubSecHFT.h 



4 




4 


PSExportDataType 


kPSExportDataNone=0, 

kPSExportDataMyContact, 

kPSExportDataContacts, 

kPSExportDataDirSettings, 

kPSExportDataEnumSize 

} PSExportDataType; 

Description 

The format of data to be exported using PSExportDataProc or 

PSExportDataExchange. 

Members 

kPSExportDataNone 

kPSExportDataMyContact 

kPSExportDataContacts 

kPSExportDataDirSettings 

kPSExportDataEnumSize 

None. No export operation is performed. 

Export certificates for self. 

This operation is performed only if the 

PROP_PSENG_ExportContact property is 

set, indicating that the handler supports this 

format. 

Export a list of entries from an address book. 


PROP_PSENG_ExportContact property is 

set, indicating that the handler supports this 

format. 

Export a list of directory settings. 


PROP_PSENG_ExportDirSettings 

property is set, indicating that the handler 

supports this format. 

The size of the enum 

Header File 

PubSecHFT.h 







4 

PSExportDestType 


kPSExportDestNone=0, 

kPSExportDestFile, 

kPSExportDestCMSFile, 

kPSExportDestCertFile, 

kPSExportDestFDFFile, 

kPSExportDestEMailFDF, 

kPSExportDestCertURL, 

kPSExportDestEnumSize 

} PSExportDestType; 

Description 

File output options for PSExportDataExchangeParams. 

Members 

kPSExportDestNone 

kPSExportDestFile 

kPSExportDestCMSFile 

kPSExportDestCertFile 

kPSExportDestFDFFile 

kPSExportDestEMailFile 

kPSExportDestCertURL 

None, prompt for output file type. 

Recommended. 

Save as unspecified file type, possibly 

prompting for the file type. 

Save as CMS file (.p7c). 

Save as Certificate file (.cer). 

Save as FDF file. 

Email FDF file. 

Send single certificate to URL. 

Header File 

PubSecHFT.h 






4 


PSImportDataExchangeParams 

typedef struct _t_PSImportDataExchangeParamsRec { 


PubSecHandler psHandler; 

PubSecEngine psEngine; 

PSExportDataType dataType; 

ASFileSys fileSys; 

ASPathName filePath; 

} PSImportDataExchangeParamsRec, *PSImportDataExchangeParams; 

Description 

Parameters for importing data from a file into PubSec. 

Members 

size 

psHandler 

psEngine 

dataType 

fileSys 

filePath 


The handler to use to accept the import data, if it accepts the specified 

type. 

The engine to use to accept the import data. If not supplied, the method 

uses the default (UI) engine. 

The type of data to be imported. If data of this type is not found in the 

FDF, the operation fails. . 

The file system used for filePath. 

The path of the file to be opened for import. 

Header File 

PubSecHFT.h 





4 

PSImportDataParams 

typedef struct _t_PSImportDataParamsRec { 


PSImportDataType dataType; 

ASCab dataCab; 

PSSigTrust sigTrust; 

} PSImportDataParamsRec, *PSImportDataParams; 

Description 

Parameters for importing data from a file into PubSec; used in PSImportDataProc. 

Members 

size 

dataType 


The format of the data to be imported. 

Header File 

dataCab ● If dataType is kPSImportDataSigDict, the signature 

dictionary. 

● If dataType is kPSImportDataFDFImportArray, the import 

array. 

● If dataType is kPSImportDataFDFDirArray, the directory 

settings array. 

sigTrust 

PubSecHFT.h 



A flag that indicates whether this data comes from a trusted source. 


4 


PSImportDataType 


kPSImportDataNone=0, 

kPSImportDataContactsCab, 

kPSImportDataContactsCabFromSig, 

kPSImportDataDirsCab, 

kPSImportDataEnumSize 

} PSImportDataType; 

Description 

The format of data to be imported using PSImportDataProc. 

The operation is only executed if the corresponding property (PROP_ImportContact or 

PROP_ImportDirSettings) is set, which indicates that the handler supports this 

format. If PROP_ImportContact is set, both of the corresponding formats must be 

supported. 

Members 

kPSImportDataNone 

kPSImportDataContactsCab 

kPSImportDataContactsCabFro 

mSig 

kPSImportDataDirsCab 

kPSImportDataEnumSize 

None. No import operation is performed. 

An ASCab containing a list ("0", "1", ...) of 

contact cabs. Contact cabs have the entries 

PROP_ContactCab_*. 

An ASCab containing a list ("0", "1", ...) 

containing a single contact cab. This Contact 

cab will have only the 

PROP_ContactCab_Certs entry set. 

This is sent only when trusting the signer of a 

signature. 

An ASCab containing a list ("0", "1", ...) of dir 

setting cabs. DirSetting cabs have the entries 

PROP_DirSettingCab_*.. 

The size of this enum 

Header File 

PubSecHFT.h 





4 

PSOpenCMSEnvelopeParams 

Members 

typedef struct _t_PSOpenCMSEnvelopeParamsRec { 


const ASUns8* cmsEnvelopeData; 

ASUns32 cmsEnvelopeSize; 

ASUns8* outEnvelopeContentsData; 

ASUns32 outEnvelopeContentsSize; 

ASUns8* outSessionKeyData; 

ASUns32 outSessionKeySize; 

ASUns8* outOpeningCertData; 

ASUns32 outOpeningCertSize; 

} PSOpenCMSEnvelopeParamsRec, *PSOpenCMSEnvelopeParams; 

size 

cmsEnvelopeData 

cmsEnvelopeSize 

outEnvelopeContentsData 

outEnvelopeContentsSize 

outSessionKeyData 

outSessionKeySize 

outOpeningCertData 

outOpeningCertSize 

The size of this structure. 

Constant. The ASN1 encoded PKCS#7 Enveloped 

Data to open. 

Size in bytes of the data pointed to by 

cmsEnvelopeData. 

Returns the envelope contents data. PubSec 

owns, allocates and frees the memory. 


cmsEnvelopeContentsData. 

Optional. Returns the session key recovered 

when opening the envelope. If a session key is 

returned by the handler, PubSec uses it to open 

other recipient groups and enable the user to 

edit them. 


outSessionKeyData. 

Optional. The certificate corresponding to the 

private key used to open the envelope. When 

provided, PubSec displayes the name of the 

opener when the user edits the recipient list. 


outOpeningCertData. 


4 


PSPerformOpType 


kPSOpPerformNone=0, 

kPSOpPerformESLogin, 

kPSOpPerformESLogout, 

kPSOpPerformESNewUser, 

kPSOpPerformESSetValidateMethod, 

kPSOpPerformESPasswordTimeout, 

kPSOpPerformDisplayCertList, 

kPSOpPerformGetCerts, 

kPSOpPerformEnumSize 

} PSPerformOpType; 

Description 

The type of operation to be performed by PSPerformOperationProc. The PubSec 

plug-in interprets relevant calls and dispatches them to handlers for the operation to be 

performed. 

Values 

kPSOpPerformNone 

kPSOpPerformESLogin 

kPSOpPerformESLogout 

kPSOpPerformESNewUser 

kPSOpPerformESSetValidateMethod 

kPSOpPerformESPasswordTimeout 

kPSOpPerformDisplayCertList 

kPSOpPerformGetCerts 

None 

Silent, scripted operations 

Brings up a UI to display a list of 

certificates contained in an ASCab. 

Returns true if implemented by the 

handler 

Returns a list of certificates in an ASCab. 

Header File 

PubSecHFT.h 


PSPerformOperationProc 



4 

PSSessionOpType 


kPSOpTypeNone=0, 

kPSOpTypePDDocSign, 

kPSOpTypePDDocSigValidate, 

kPSOpTypeCosDocSign, 

kPSOpTypeCosDocSigValidate, 

kPSOpTypeDataSign, 

kPSOpTypeDataSigValidate, 

kPSOpTypeMyContactExport, 

kPSOpTypeContactImport, 

kPSOpTypePolicyModify, 

kPSOpTypeAPRead, 

kPSOpTypePDCryptDocCreate, 

kPSOpTypePDCryptDocOpen, 

kPSOpTypeLogin, 

kPSOpTypeLogout, 

kPSOpTypeCertEnum, 

kPSOpTypeDirEnum, 

kPSOpTypeDirGet 

} PSSessionOpType; 

Description 

Operations for which a PubSec session can be acquired. 

Values 

kPSOpTypeNone 

kPSOpTypePDDocSign 

kPSOpTypePDDocSigValidate 

kPSOpTypeCosDocSign 

kPSOpTypeCosDocSigValidate 

kPSOpTypeDataSign 

kPSOpTypeDataSigValidate 

kPSOpTypeMyContactExport 

kPSOpTypeContactImport 

None 

Sign a PDDoc to create a PDDoc signature. 

Validate a PDDoc signature. 

Sign a cosDoc. 

Validate a cosDoc signature. 

Sign bytes. 

Validate bytes. 

Read and export My Contact information. 

Import contacts into address book. 


4 


kPSOpTypePolicyModify 

kPSOpTypeAPRead 

kPSOpTypePDCryptDocCreate 

kPSOpTypePDCryptDocOpen 

kPSOpTypeLogin 

kPSOpTypeLogout 

kPSOpTypeCertEnum 

kPSOpTypeDirEnum 

kPSOpTypeDirGet 

Modify credential access policy (used by EScript). 

Read an appearance file (used by EScript). 

Prepare to encrypt docsuments. 

Prepare to open encrypted documents. 

Authenticate or login user (used by EScript). 

De-authenticate or logout user (used by EScript). 

Enumerate certificates available for signing and 

encryption. 

Enumerate directories and get directory 

information. 

Connect to and use directory. 

Header File 

PubSecHFT.h 







4 

PSSigCosDocParams 

typedef struct _t_PSSigCosDocParamsRec { 


PSSigDocType sigType; 

PDDoc pdDoc; 

CosDoc cosDoc; 

CosObj sigDict; 

} PSSigCosDocParamsRec, *PSSigCosDocParams; 

Description 

Signature parameters for a cosDoc. Used internally. 

Members 

size 

sigType 

pdDoc 

cosDoc 

sigDict 


Constant. Always kPSSigDocTypeCosDoc. 

Constant. Null if no parent. 

Constant. The document being signed. 

Constant. The signature dictionary. 

Header File 

PubSecHFT.h 




PSSigSigPropParams 


4 


PSSigDataBufferParams 

typedef struct _t_PSSigDataBufferParamsRec { 



PDDoc pdDoc; 


} PSSigDataBufferParamsRec, *PSSigDataBufferParams; 

Description 

Signature parameters for signing transitional data, such as XFA. 

Members 

size 

sigType 

pdDoc 

cosDoc 


Constant. Always kPSSigDocTypeCosDoc. 

Constant. NULL if no parent. 


Header File 

PubSecHFT.h 







4 

PSSigDocType 


kPSSigDocTypeNone=0, 

kPSSigDocTypePDDoc, 

kPSSigDocTypeCosDoc, 

kPSSigDocTypeTransData, 

kPSSigDocTypeEnumSize 

} PSSigDocType; 

Description 

The type of document being signed. 

Values 

kPSSigDocTypePDDoc 

kPSSigDocTypeCosDoc 

kPSSigDocTypeTransData 

A PDF document. 

An FDF file. 

Reserved for future use. 

Header File 

PubSecHFT.h 


PSSigPDDocParams 




4 


PSSigDialogStatus 


kPSSigDialogNone=0, 

kPSSigDialogSign, 

kPSSigDialogSignWithPassword, 

kPSSigDialogSignThenAuthenticate, 

kPSSigDialogStatusEnumSize 

} PSSigDialogStatus; 

Description 

Dialog information returned from PSSigGetSigPropertiesProc and other calls to 

tell PubSec what flow of subsequent dialogs or actions to execute. Not all values are legal 

for all calling procedures. 

Values 

kPSSigDialogNone 

kPSSigDialogSign 

kPSSigDialogSignWithPassword 

kPSSigDialogSignThenAuthenticate 

No further dialogs required. 

PubSec's sign dialog should be 

executed 


executed, and ask for password. 


executed, then SigAuthenticate 

should be called. 







4 

PSSigFileType 


kPSFileNone=0, 

kPSFileAVDoc, 

kPSFileBrowserDoc, 

kPSFileExternalDoc, 

kPSFileTempDoc, 

kPSFileFDFData, 

kPSFileCosDoc, 

kPSFileTransData, 

kPSFileEnumSize 

} PSSigFileType; 

Description 

A constant value that indicates the file type and environment in which data is being signed, 

used to set up buttons and text in the signing dialog. 

Values 

kPSFileNone 

kPSFileAVDoc 

kPSFileBrowserDoc 

kPSFileExternalDoc 

kPSFileTempDoc 

kPSFileFDFData 

kPSFileCosDoc 

kPSFileTransData 

Uninitialized. 

Normal PDDoc signing. Enable Save and SaveAs buttons 

Signing a PDDoc in an external browser window. Enable 

Sign button. 

Signing a PDDoc in an external non-browser window. 

Enable Sign button. 

Signing a temporary file. Enable SaveAs button 

Signing an FDF Data Exchange file. Enable Sign button. 

Signing a cosDoc. Enable Sign button. 

Signing transactional data. 

Header File 

PubSecHFT.h 




4 


PSSigMethod 


kPSSigMethodNone=0, 

kPSSigMethodPKCS1, 

kPSSigMethodPKCS7Detached, 

kPSSigMethodPKCS7SHA1, 

kPSSigMethodEnumSize 

} PSSigMethod; 

Description 

Constants that specify the method to use for creating a signature. For details, see the PDF 

Reference. 

Values 

kPSSigMethodNone 

kPSSigMethodPKCS1 

kPSSigMethodPKCS7Detached 

kPSSigMethodPKCS7SHA1 

None 

PKCS#1, adbe.x509.rsa.sha1 

adbe.pkcs7.detached 

adbe.pkcs7.sha1 

Header File 

PubSecHFT.h 


PSSigGetSigValueParams 





4 

PSSigPDDocParams 

typedef struct _t_PSSigPDDocParamsRec { 



PDDoc pdDoc; 

CosObj sigField; 

CosObj sigAnnot; 

ASFixed annotWidth; 

ASFixed annotHeight; 

ASCab sigAPCab; 

} PSSigPDDocParamsRec, *PSSigPDDocParams; 

Description 

Validation parameters for validating a document signature or specific signature field. 

Members 

size 

sigType 

pdDoc 

sigField 

sigAnnot 

annotWidth 

annotHeight 

sigAPCab 


Constant. Always kPSSigDocTypePDDoc. 


Constant. The field being signed. 

Constant. The annotation associated with this field. 

Constant. Width of the annotion if the signature is visible. 

Constant. Height of the annotion if the signature is visible. 

Returns handler-specific appearance information for 

PSSigGetSigPropertiesProc. 

Header File 

PubSecHFT.h 


PSSigValidatePDDocSigField 







4 


PSSigGetSigValueParams 

typedef struct _t_PSSigGetSigValueParamsRec { 


PSSigMethod sigMethod; 

DSDigestMethod digestMethod; 

const ASUns8* digestValue; 

PSDataBuffer dataBuffer; 

ASBool bGetSigValue; 

ASUns8* outSigValueData; 

ASUns32 outSigValueSize; 

ASCab outSigPropCab; 

} PSSigGetSigValueParamsRec, *PSSigGetSigValueParams; 

Description 

A structure containing parameters and return values for PSSigGetSigValueProc. 

Members 

size 

sigMethod 

digestMethod 

digestValue 

dataBuffer 

bGetSigValue 

outSigValueData 

outSigValueSize 

outSigPropCab 


Constant. The method used to create the 

signature value. 


digest. 

Constant. A digest value to be signed or NULL. 

The handle to use for fetching bytes to digest. 

Constant. If true, get a signature value, 

otherwise return the size of the signature 

value. 

Return the signature value data. Caller will call 

ASfree to destroy the structure. 

Return size of the signature value. 

Return an ASCab containing signature 

properties that should be displayed instead of 

signature dictionary entries. 

Header File 

PubSecHFT.h 



4 




4 



typedef struct _t_PSSigSigPropParamsRec { 


PDDoc pdDoc; 

PSSigFileType fileOptions; 

ASBool bUI; 

ASText dialogTitle; 

ASCab sigParamsCab; 

DSSaveType outSaveOptions; 

PSSigDialogStatus outDialogStatus; 

ASCab outCertListCab; 

ASCab outNewSigPropCab; 

ASCab outNewSigBuildCab; 

PSSigDocType docType; 

void* docParams; 

} PSSigSigPropParamsRec, *PSSigSigPropParams; 

Description 

A structure containing parameters and return values for 

PSSigGetSigPropertiesProc. 

Members 

size 


pdDoc Constant. The pdDoc being signed. If not signing a pdDoc , 

this is only used for window parenting and can be NULL. 

fileOptions 

bUI 

dialogTitle 

sigParamsCab 

outSaveOptions 

Constant. The file type and signing environment, which the 

handler uses to put up appropriate save buttons. 

Constant. When true , the call is being made from the UI, 

when false it is being made from a script or batch file. 

Title to use for the signing dialog, if bUI is true. Usually 

NULL, which allows the handler to use the default. 

Constant. Parameters passed in by EScript converted to an 

ASCab, or NULL if the call is not from EScript. 

If not providing your own sign dialog, set this value to 

DSSignSave. 

If providing your own sign dialog, return the result of your 

sign dialog. Setting the value to DSignCancel cancels the 

signing operation. 



4 

outDialogStatus 

outCertListCab 

outNewSigPropCab 

outNewSigBuildCab 

docType 

docParams 

Return status information that tells PubSec what dialogs to 

put up and how to authenticate the handler. 

Required. Return an ASCab containing an ordered certificate 

chain, signing certificate first (at key 0). 

Required. Populate this existing ASCab with signature 

properties that will be written to the signature dictionary 

when the signature is committed. 

Optional. Populate this existing ASCab with return build 

properties that will be written to the signature dictionary 

when the signature is committed. 

Constant. The type of document being signed. 

A structure containing signature parameters appropriate to 

the type of document. Depending on sigType, a structure 

of type PSSigPDDocParams, PSSigCosDocParams, or 

PSSigDataBufferParams. 

Header File 

PubSecHFT.h 




4 


PSSigTrust 

Description 

Bit flag constants that specify a level of trust for a certificate. 

Values 

kPSSigTrustUntrusted 

kPSSigTrustSigning 

kPSSigTrustAuthenticDocuments 

kPSSigTrustDynamicContent 

kPSSigTrustUbiquity 

kPSSigTrustJavaScript 

kPSSigTrustAll 

Certificate is untrusted. 

Trusted for signing (creating recipient 

signatures). 

Trusted for authoring documents (creating 

author signatures). 

Trusted for authoring documents with 

dyamic (multimedia) content. 

Trusted for feature-enabling signatures 

(Adobe internal use only). 

Trusted for authoring documents with fullaccess 

JavaScript. 

Trusted for everything. 

Header File 

PubSecHFT.h 




PSImportDataParams 



4 

PSSigValidateParams 

typedef struct _t_PSSigValidateParamsRec { 


PSSigMethod sigMethod; 

DSDigestMethod digestMethod; 

ASUns8* digestValue; 

ASUns8* sigValueData; 

ASUns32 sigValueSize; 

ASCab certListCab; 

ASBool reqRevokeChecks; 

ASInt32 maxRevokeInfoCacheLifetime; 

ASCab sigValCab; 

ASCab outSigPropCab; 

PSDataBuffer dataBuffer; 

} PSSigValidateParamsRec, *PSSigValidateParams; 

Description 

A structure containing parameters and return values for PSSigValidateProc. 

Members 

size 

sigMethod 

digestMethod 

digestValue 

sigValueData 

sigValueSize 

certListCab 



signature value. 


digest. 

Constant. A digest value to be signed or NULL. 

Constant. A signature value to be verified. 

Constant. The size of the signature value. 

In and out. 

● For a PKCS#1 signature, PubSec fills in the 

certificate chain. 

● For a PKCS#7 signature, PubSec returns an 

empty ASCab. 

For both signature types, the handler must 

provide the certificate chain that was validated. 


4 


reqRevokeChecks 

maxRevokeInfoCacheLifetime 

sigValCab 

outSigPropCab 

dataBuffer 

Informs the handler whether revocation checks 

are required. Handlers should always do 

revocation checks, but return failure only when 

this value is true. 

The maximum life time (in minutes) of the 

cached information that is used for revocation 

checking. This is relevant for some types of 

revocation checking (such as CRL-based) and 

not for others (such as OCSP). 

Returns an ASCab containing the validity of 

the signature. Must not be NULL. 

The handler must set the values for 

PROP_SigVal_Id and 

PROP_SigVal_TrustFlags, and can 

optionally set PROP_SigVal_IdPriv. The 

handler should also set the value of 

PROP_SigVal_Digest if it is not already 

set. All other values should be left unmodified. 

Returns signature properties to display instead 

of signature dictionary entries. 

The handle to use for fetching bytes to digest. 

Header File 

PubSecHFT.h 





4 


typedef struct _t_PSSigValidateDialogParamsRec { 


ASCab certListCab; 

ASBool reqRevokeChecks; 

ASInt32 maxRevokeInfoCacheLifetime; 

ASCab sigValCab; 

ASBool bModalParent; 

DSPropertyType dsPropType; 

PSSigDocType docType; 

void* docParams; 

} PSSigValidateDialogParamsRec, *PSSigValidateDialogParams; 

Description 

A structure containing parameters and return values for PSSigValidateDialogProc. 

Members 

size 

certListCab 

reqRevokeChecks 

maxRevokeInfoCacheLifetime 

sigValCab 


In and out. 

● For a PKCS#1 signature, PubSec fills in the 

certificate chain. 

● For a PKCS#7 signature, PubSec returns an 

empty ASCab. 

For both signature types, the handler must 

provide the certificate chain that was validated. 

Informs the handler whether revocation checks 

are required. Handlers should always do 

revocation checks, but return failure only when 

this value is true. 

The maximum life time (in minutes) of the 

cached information that is used for revocation 

checking. This is relevant for some types of 

revocation checking (such as CRL-based) and 

not for others (such as OCSP). 

An ASCab containing the validity of the 

signature. Never NULL. 

The handler can validate the signature and 

update this object if desired. 


4 


bModalParent 

dsPropType 

docType 

docParams 

Indicates whether being called when a modal 

parent dialog is open. If true, rollback and 

verify buttons should be disabled because 

i) rollback is not possible while modal parent is 

open; (ii) verify status may not get propagated 

properly to various caching locations. 

Returns a value that tells PubSec whether to 

rollback the signature or show a properties 

dialog for the signature. 

Constant. The type of document being signed. 

A structure containing signature parameters 

appropriate to the type of document. 

Depending on sigType, a structure of type 

PSSigPDDocParams or 

PSSigCosDocParams. 

Header File 

PubSecHFT.h 





4 

PSSigValidateSupportParams 

typedef struct _t_PSSigValidateSupportParamsRec { 


ASAtom filter; 

ASAtom subFilter; 

ASInt32 version; 

ASInt32 revision; 

ASCab buildCab; 

} PSSigValidateSupportParamsRec, *PSSigValidateSupportParams; 

Description 

A structure containing signature parameters for PSSigValidateSupportedProc. 

Members 

size 

filter 

subFilter 

version 

revision 

buildCab 


Constant. The value of the /Filter attribute for the signature. 

Constant. The value of the /SubFilter attribute for the signature. 

Constant. The value of the /V attribute for the signature. 

Constant. The value of the /R attribute for the signature. 

Constant. The handler’s build properties dictionary, as an ASCab. 

Header File 

PubSecHFT.h 




4 


PSSigValSupport 


kPSSigValSupportFalse, 

kPSSigValSupportTrue, 

kPSSigValSupportUpdate, 

kPSSigValSupportPreRelease, 

kPSSigValSupportEnumSize 

} PSSigValSupport; 

Description 

Constant values indicating how a handler supports validation for a particular signature. 

Values 

kPSSigValSupportFalse 

kPSSigValSupportTrue 

kPSSigValSupportUpdate 

kPSSigValSupportPreRelease 

The handler does not support validationof this 

signature. 

The handler supports validationof this 

signature. 

A handler software update is needed to 

support validation of this signature. 

The signature was created with a pre-release 

or invalid release of the software. Warns user. 

Header File 

PubSecHFT.h 





4 

PubSecEngine 

typedef void* PubSecEngine; 

Description 

A PubSec engine object. There can be multiple engine objects per handler. 

Header File 

PubSecHFT.h 





4 


PubSecHandler 

typedef struct _t_PubSecHandlerRec { 


_t_PubSecHandlerRec *next; /*used internally*/ 

DigSigHandler dsHandler; /*used internally*/ 

PDCryptHandler cryptHandler; /*used internally*/ 

PubSecEngine engine; 

PSNewEngineProc newEngine; 

PSDestroyEngineProc destroyEngine; 

PSGetBoolPropertyProc getBoolProperty; 

PSGetAtomPropertyProc getAtomProperty; 

PSGetInt32PropertyProc getInt32Property; 

PSGetTextPropertyProc getTextProperty; 

PSSessionAcquireProc sessionAcquire; 

PSSessionReleaseProc sessionRelease; 

PSSessionReadyProc sessionReady; 

PSPerformOperationProc performOperation; 

PSSigGetSigPropertiesProc sigGetSigProperties; 

PSSigAuthenticateProc sigAuthenticate; 

PSSigGetSigValueProc sigGetSigValue; 

PSSigValidateProc sigValidate; 

PSSigValidateDialogProc sigValidateDialog; 

PSSigPropDialogProc sigPropDialog; 

PSSigValGetTextProc sigValGetText; 

PSGetLogoProc getLogo; 

PSSigValGetAPLabelProc sigValGetAPLabel; 

PSSigCreateAPNXObjProc sigCreateAPNXObj; 

PSImportDataProc importData; 

PSExportDataProc exportData; 

PSOpenCMSEnvelopeProc cryptOpenCMSEnvelope; 

PSGetImplicitRecipientsProc cryptGetImplicitRecipients; 

PSGetDirHandlerInfo dirGetDirHandlerInfo; 

PSGetDirList dirGetDirList; 

PSGetDirInfo dirGetDirInfo; 

PSSetDirInfo dirSetDirInfo; 

PSOpenConnection dirOpenConnection; 

} PubSecHandlerRec, *PubSecHandler; 

Description 

A handler structure that specifies the callbacks to register for a PubSec engine. 

Members 

size 




4 

next 

dsHandler 

cryptHandler 

engine 

newEngine 

destroyEngine 

getBoolProperty 

getAtomProperty 

getInt32Property 

getTextProperty 

sessionAcquire 

sessionRelease 

sessionReady 

performOperation 

sigGetSigProperties 

sigAuthenticate 

sigGetSigValue 

sigValidate 

sigValidateDialog 

sigPropDialog 

sigValGetText 

sigValGetText 

getLogo 

sigValGetAPLabel 

sigCreateAPNXObj 

importData 

exportData 

cryptOpenCMSEnvelope 

cryptGetImplicitRecipients 

dirGetDirHandlerInfo 

dirGetDirList 

dirGetDirInfo 

dirSetDirInfo 

dirOpenConnection 

Used internally. 

Engine to use for UI-based execution. 

Engine constructor and destructor. 

Property retrieval methods. 

Session operation methods. 

Signature methods. 

Validation methods 

Signature appearance methods. 

Contact exchange methods. 

Encryption methods. 

Directory Service Provider methods. 


4 


Header File 

PubSecHFT.h 






4 


4 



5 

Digital Signature Methods 

DigSigAddedSig 

void DigSigAddedSig (PDDoc pdDoc); 

Description 

Recalculates the number of signature fields and redraws the signature panel after any 

signature is added. 

Called by the AcroForm plug-in or any agent that adds a signature field. 

Parameters 

pdDoc 

The document that contains the signature field. 

Return Value 

None 

Header File 

DigSigHFT.h 


DigSigAddedSigEx 

DigSigDeletedSig 


5 



void DigSigAddedSigEx (PDDoc pdDoc, CosObj cosField); 

Description 

Recalculates the number of signature fields and redraws the signature panel after a 

specified signature field is added. 

This version, added in Acrobat 6.0, is more efficient than DigSigAddedSig, but requires 

that you specify the signature field that is being added. 

Parameters 

pdDoc 

cosField 


The signature field that was added. 

Return Value 

None 

Header File 

DigSigHFT.h 



DigSigDeletedSigEx 



5 

DSAPCreateCompositeTextXObj 

CosObj DSAPCreateCompositeTextXObj (const CosDoc cosDoc, 

const DSAPTextEntry inText, const ASFixedRect* const bbox, 

const CosObj sigField, const CosObj sigAnnot 

Description 

Creates an new XObject that consists of vertically stacked blocks of text where each block is 

automatically sized to fit it own bounding box. 

Parameters 

cosDoc 

inText 

bbox 

sigField 

sigAnnot 

The document. 

The text to include. 

The bounding box, which must already compensate for rotation and 

position within the annotation. 

The signature field object. 

The signature annotation object. 

Return Value 

The new XObject that contains the text. 

Header File 

DigSigHFT.h 


DigSigAPXObjectFromLogo 

DigSigAPXObjectFromXObjList 


5 


DigSigAPCreateLayeredStream 

Description 

Parameters 

CosObj DigSigAPCreateLayeredStream(const CosDoc cosDoc, 

const CosObj layer1XObject, ASFixedMatrixP layer1Matrix, 

const CosObj layer2XObject, ASFixedMatrixP layer2Matrix, 

const CosObj layer3Matrix, ASFixedMatrixP layer3Matrix, 

const CosObj layerNXObject, ASFixedMatrixP layerNMatrix, 

ASInt16 layerNNum, AFPDWidgetBorder border, 

PDColorValue cBorder, PDColorValue cBackGnd, ASFixed width, 

ASFixed height, PDRotate pdr); 

N OTE: Superceded by DigSigAPCreateLayeredStreamEx in Acrobat 6.0. 

Creates a stream that is composed of either four or five layers: 

● layer 0: background, inherited from form annot background 

● layer 1: middle, question mark or equivalent (uses the default if layer1XObject is 

CosNull) 

● layer 2: main, text and appearance (must be provided) 

● layer 3: top, blank or X (uses the default if layer1XObject is CosNull) 

● layer N: optional very top layer, used for text showing validity state (none if CosNull) 

cosDoc 

layer1XObject 

layer1Matrix 

layer2XObject 

layer2Matrix 

layer3XObject 

layer3Matrix 

layerNXObject 

layerNum 

border 

cBorder 

The document in which to include the standard XObject. 

The middle layer. 

The position the first layer object. 

The text and appearance layer. 

The position the second layer object. 

The top layer. 

The position the third layer object. 

An optional validity state layer. 

The layer number for the optional validity state layer. 

The border from AFPDWidgetGetBorder. 

The color of the border. 



5 

cBackGnd 

width 

height 

pdr 

color of the background. 

The width of the new stream object. 

The height of the new stream object. 

The rotational parameter from AFPDWidgerGetRotation. 

Return Values 

A new CosStream composed of different layers. 

Header File 

DigSigHFT.h 





5 


DigSigAPCreateLayeredStreamEx 

CosObj DigSigAPCreateLayeredStreamEx 

(const DSAPCreateLayeredStreamExParams params) 

Description 

Creates a signature-appearance layered stream, using a parameters structure. 

Parameters 

N OTE: Supersedes DigSigAPCreateLayeredStream in Acrobat 6.0. 

params 

The parameter structure containing the signature appearance layer 

information. 

Return Values 

A new CosStream composed of different layers. 

Header File 

DigSigHFT.h 






5 


CosObj DigSigAPXObjectFromLogo (const CosDoc cosDoc, 

const char* logoStr, const ASInt32 logoStrSize, 

const ASFixedRect* const logoBBox, 

const ASFixedRect* const bbox); 

Description 

Takes text for a stream logoStr with bounding box logoBBox and fits it precisely to 

bbox. Performs uniform x and y scaling, and x-y translation. Can raise an exception. This 

method might throw, and should be wrapped in a DURING/HANDLER block. 

Parameters 

cosDoc 

logoStr 

logoStrSize 

logoBbox 

bbox 

The document. 

The stream containing the text. 

The length of the logo string, or 0 to calculate the length 

automatically. 

The bounding box for logoStr. 

The bounding rectangle of the result. 

Return Value 

A Cos object XObject that contains the logo. 

Header File 

DigSigHFT.h 






5 



CosObj DigSigAPXObjectFromXObjList (CosDoc cosDoc, 

const ASFixedRect* const bbox, DSAPXObjEntry objEntry, 

TextAppearanceP ta, AFPDWidgetBorder border, ASBool bMerge); 

Description 

Creates a new XObject from the list of DSAPXObjEntry objects. Each object in the list is 

either an existing stream or a string that will be laid out and reflowed into a new stream. 

The streams are then turned into XObjects. Controls allow you to adjust the vertical 

position of each stream within bbox. If bMerge is true then this method combines the 

new XObjects into one large XObject, and the sub XObjects are destroyed. Otherwise the 

method leaves the component XObjects intact and new XObjects are created but not 

destroyed for the text entries. Text streams use the text attributes of ta. 

Parameters 

cosDoc 

bbox 

objEntry 

ta 

border 

bMerge 


The bounding box for the signature. 

A list of DSAPXObjEntry objects. 

The text appearance. 

For an explanation of the TextAppearanceP type, see "AcroForm 

Declarations" in Acrobat Forms API Reference. 

The border style for the signature, as returned by 

AFPDWidgetGetBorder . 

For an explanation of the AFPDWidgetBorder type, see "AcroForm 

Declarations" in Acrobat Forms API Reference. 

When false, keep sub XObjects. When true, combine them all into 

one large one. 

Return Value 

XObject composed from list. 

Header File 

DigSigHFT.h 







5 

DigSigByteToHex 

void DigSigByteToHex (unsigned char* byteP, 

unsigned char* hexP, ASInt32 length); 

Description 

Converts a byte string to a PDF hex string. 

Parameters 

byteP 

hexP 

length 

A pointer to the byte string. 

(Filled by the method) A pointer to an output buffer to hold the hex string. 

Must be at least (length * 2) + 3 bytes. The string begins with “”, followed by a NULL character. For example, the two byte string 

“A/” is converted to “\0.” 

The length of the byte string, in bytes 

Return Value 

None 

Header File 

DigSigHFT.h 


DigSigHexToByte 


5 


DigSigClearSig 

void DigSigClearSig (PDDoc pdDoc, CosObj sigField); 

Description 

Clears a signature field in a document. This removes the signature, so that the document is 

unsigned. 

Parameters 

pdDoc 

sigField 

The document. 

The signature field to clear. 

Return Value 

None 

Header File 

DigSigHFT.h 


DigSigVerifySig 



5 

DigSigClearSigRefDict 

DSRetCode DigSigClearSigRefDict (ASAtom transformMethod, 

CosObj sigDict, CosObj refDict ); 

Description 

Clears the signature reference dictionary referred to by refDict and removes any 

reference to it from the document. 

Parameters 

transformMethod 

sigDict 

refDict 

The transform method. It should match the one contained in 

sigDict. 

The signature dictionary containing the signature reference 

dictionary. 

The signature reference dictionary. 

Return Value 


Header File 

DigSigHFT.h 


DigSigCommitSigRefDict 

DigSigFinishSigRefDict 

DigSigNewSigRefDict 

DigSigVerifySigRefDict 


5 


DigSigClick 

void DigSigClick (PDAnnot pdAnnot, AVPageView avPV, 

ASInt16 nX, ASInt16 nY, ASInt16 nFlags, ASInt16 nClicks); 

Description 

The AcroForm plug-in calls this method when a user left-clicks inside a signature 

annotation. 

Parameters 

pdAnnot 

avPV 

nX 

nY 

nFlags 

nClicks 

The annotation the user clicked on 

The page view that contains the annotation. 

The x-coordinate of the mouse click, specified in device space coordinates. 

The y-coordinate of the mouse click, specified in device space coordinates. 

Indicates which modifier keys are pressed, if any. Must be an OR of the 

Modifier Keys values, which are the following: 

● AV_COMMAND 

● AV_OPTION 

● AV_CONTROL 

● AV_SHIFT 

The number of clicks. 

Return Value 

None 

Header File 

DigSigHFT.h 


DigSigDraw 


DigSigRightClick 



5 


DSRetCode DigSigCommitSigRefDict (ASAtom transformMethod, 

CosObj sigDict, CosObj pOutRefDict ); 

Description 

Adds a signature reference dictionary to the document and saves the document. 

This method uses the information that was provided in the DSSigRefDictErrParams 

parameter block during the call toDigSigNewSigRefDict.transformMethod and 

sigDict should match the values provided at that time. 

After this operation, some of the values in the reference dictionary are still dummy values, 

including DigestValue and DigestLocation (see Section 8.7, "Digital Signatures" in the PDF 

Reference for more information). DigSigFinishSigRefDict should be called next to 

fill in these values. 

If signing is cancelled after this operation, DigSigClearSigRefDict should be called 

to remove all references to the reference dictionary from the document. 

Parameters 

transformMethod The transform method. 

sigDict 

refDict 

The signature dictionary that contains the signature reference 

dictionary. 

(Filled by the method) A pointer to the committed signature 

reference dictionary. 

Return Value 

kDSTrue on success; kDSFalse on parameter error; kDSException for all other errors. 

Header File 

DigSigHFT.h 







5 


DigSigComparePages 

ASBool DigSigComparePages (PDDoc docA, PDDoc docB, 

ASBool insertDiffs); 

Description 

Compares the pages of two documents, producing a third document of the differences. 

Parameters 

N OTE: Superceded by DigSigComparePagesEx in Acrobat 6.0. 

docA 

docB 

insertDiffs 

First document to compare. 

Second document to compare. 

Not used. 

Return Value 

true if the pages of the documents are identical, false otherwise. 

Header File 

DigSigHFT.h 


DigSigCompareWords 



5 

DigSigComparePagesEx 

ASBool DigSigComparePagesEx (PDDoc docA, PDDoc docB, 

DSComparePagesParams params); 

Description 

Compares the pages of two documents, producing a third document of the differences. 

Parameters 

docA 

docB 

params 

First document being compared. 

Second document being compared. 

A structure containing the sensitivity level for the comparison. 

Return Value 

true if the pages of the documents are identical, false otherwise. 

Header File 

DigSigHFT.h 





5 



ASBool DigSigCompareWords (PDDoc docA, PDDoc docB, 

ASBool iUseFonts); 

Description 

Compares the words of two documents, producing a third document of the differences. 

Parameters 

N OTE: Superceded by DigSigCompareWordsEx in Acrobat 6.0. 

docA 

docB 

iUseFonts 



If true, the font name, size, and color of each character in a word are 

considered when matching against other words. If false, these 

attributes are ignored. 

Return Value 

true if the words of the documents are identical, false otherwise. 

Header File 

DigSigHFT.h 



DigSigCompareWordsAndFontsRecent 

DigSigCompareWordsEx 

DigSigCompareWordsRecent 



5 


ASBool DigSigCompareWordsAndFontsRecent (PDDoc docA, 

PDDoc docB, ASBool iUseFonts); 

Description 

Compares the words of two documents, taking into account possible font changes, and 

produced a third document of the differences. 

Parameters 


docA 

docB 

iUseFonts 






Return Value 


Header File 

DigSigHFT.h 







5 



ASBool DigSigCompareWordsEx (PDDoc docA, PDDoc docB, 

DSCompareWordsParams params); 

Description 


N OTE: 

Supercedes DigSigCompareWords, 

DigSigCompareWordsAndFontsRecent, and 

DigSigCompareWordsRecent in Acrobat 6.0. 

Parameters 

docA 

docB 

params 



A structure containing the comparison parameters. 

Return Value 


Header File 

DigSigHFT.h 








5 


ASBool DigSigCompareWordsRecent (PDDoc docA, PDDoc docB, 

ASBool iUseFonts); 

Description 


Parameters 


docA 

docB 

iUseFonts 






Return Value 


Header File 

DigSigHFT.h 







5 


DigSigCosObjOverwrite 

ASInt32 DigSigCosObjOverwrite (ASFile asFile, 

const DigSigOffset digSigOffset, const CosObj cosObj, 

DSOverwriteType dsOverwriteType); 

Description 

Overwrites the part of a file containing the specified cosObj, which contains data of the 

specified type. Reopens the file for write, positions to the specified location, and directly 

writes the characters, as appropriate to the type. 

Introduced in Acrobat 6.0. 

Parameters 

asFile 

digSigOffset 

cosObj 

dsOverwriteType 

The file containing the cosObj. 

The location of the cosObj in the file, with the byte 

position and number of bytes to overwrite. 

● Does not write and returns 0 if the formatted length 

is longer than the length in digSigOffset. 

● Writes padding spaces to the file if formatted length 

is less than the length in digSigOffset. 

The cosString to be written. 

Does not write and returns 0 if there are any illegal 

characters in the string. 

The type of overwrite to perform. 

● DSOverwriteStringHex (equivalent to calling 

DigSigOverwriteHexstring) 

● DSOverwriteArray (equivalent to calling 

DigSigOverwriteIntArray) 

● DSOverwriteStringBase64 

Return Value 

Non-zero if successful. 0 if the formatted length is longer than the length in 

digSigOffset, or if there are any illegal characters in the string. 

Header File 

DigSigHFT.h 


DigSigFileGetEOF 

DigSigFileSetPos 

DigSigFileRead 

DigSigOverwriteBytes 



5 

DigSigOverwriteHexstring 

DigSigOverwriteIntArray 


5 


DigSigCreateStdXObj 

CosObj DigSigCreateStdXObj (const CosDoc cosDoc, 

const ASFixedRect* pBBoxRec, DSXObjType dsXObjType); 

Description 

Returns a new XObject with the specified bounding box. Unlike the XObject returned by 

DigSigGetStdXObj, DigSig does not attach the XObject returned by this function to the 

CosDoc. 

Parameters 

cosDoc 

pBBoxRec 

dsXObjType 

The document containing the new object. 

A pointer to desired bounding box. 

The type of object to create. 

Return Value 

A CosObj containing the new XObject form, or CosNewNull if unsuccessful 

Header File 

DigSigHFT.h 


DigSigGetStdXObj 



5 


void DigSigDeletedSig (PDDoc pdDoc); 

Description 

Recalculates the number of signature fields and redraws the signature panel after any 

signature is deleted. 

Called by the AcroForm plug-in or any agent that deletes a signature field. 

Parameters 

pdDoc 

The document that contains a signature field. 

Return Value 

None 

Header File 

DigSigHFT.h 





5 



void DigSigDeletedSigEx (PDDoc pdDoc, CosObj cosField); 

Description 

Recalculates the number of signature fields and redraws the signature panel after a 

specified signature is deleted. 

This version, added in Acrobat 6.0, is more efficient than DigSigDeletedSig, but 

requires that you specify the signature field that is being deleted. 

Parameters 

pdDoc 

cosField 

The document that contained the signature field. 

The signature field that was deleted. 

Return Value 

None 

Header File 

DigSigHFT.h 






5 

DigSigDocModifiedAfterSig 

ASBool DigSigDocModifiedAfterSig (PDDoc doc, CosObj sigField); 

Description 

Tests whether a document has been modified since being signed with the specified 

signature. 

Parameters 

pdDoc 

sigfield 

The document containing the signature field. 

The signature field. 

Return Value 

ASBool true if the document has been modified, false otherwise. 

Header File 

DigSigHFT.h 


None 


5 


DigSigDoProperties 

void DigSigDoProperties (AVDoc avDoc, CosObj sigField); 

Description 

Opens DigSig’s property dialog. 

Parameters 

avDoc 

sigField 


The signature field of the document. 

Return Value 

None 

Header File 

DigSigHFT.h 


None 



5 

DigSigDraw 

void DigSigDraw (PDAnnot pdAnnot, AVPageView avPV, 

ASBool bIsSelected); 

Description 

Causes the signature to be redrawn. 

Parameters 

pdAnnot 

avPV 

blsSelected 

The annotation the user clicked on or tabbed into 

The page view that contains the annotation 

true if the annotation is selected, false otherwise 

Return Value 

None 

Header File 

DigSigHFT.h 





5 


DigSigEnumSignatures 

void DigSigEnumSignatures (PDDoc pdDoc, DigSigEnumProc proc, 

void *clientData); 

Description 

Enumerates the signature fields (signed and unsigned) in the file. 

Parameters 

pdDoc 

proc 

clientData 


The procedure to call once for each existing signature. 

Pointer to user-supplied data to pass to proc each time it is called. 

Return Value 

None 

Header File 

DigSigHFT.h 


DigSigEnumProc 



5 


ASInt32 DigSigFileGetEOF (ASFile asFile); 

Description 

Gets the number of bytes in an ASFile. Serves as a wrapper for the ASFileGetEOF 

method. 

Parameters 

asFile 

The ASFile whose length is obtained. 

Return Value 

Number of bytes in the ASFile, or 0 if an error is encountered. 

Header File 

DigSigHFT.h 








5 



ASInt32 DigSigFileRead (ASFile asFile, char* p, 

ASInt32 count); 

Description 

Reads from an ASFile. This is a wrapper function for the ASFileRead method. 

Parameters 

asFile 

p 

count 

The ASFile to read. 

Pointer to a buffer. 

Number of bytes to read into the buffer. 

Return Value 

Number of bytes read, or 0 if unsuccessful. 

Header File 

DigSigHFT.h 









5 


void DigSigFileSetPos (ASFile asFile, ASInt32 pos); 

Description 

Reopens an ASFile for reading and sets the file position. 

Parameters 

asFile 

pos 

The ASFile to position. 

The byte offset to a position in asFile 

Return Value 

None 

Header File 

DigSigHFT.h 








5 



DSRetCode DigSigFinishSigRefDict (ASAtom transformMethod, 

CosObj sigDict, CosObj refDict, 

DSSigRefDictErrParams errParams); 

Description 

Computes the digest value and stores it in the reference dictionary. It should be called after 

DigSigCommitSigRefDict. 

Parameters 

transformMethod The transform method used to calculate the digest. It must 

match originally specified in DigSigNewSigRefDict 

sigDict The signature dictionary that contains the signature 


refDict 

errParams 

The reference dictionary returned from the call to 


A structure containing information about an exception. 

Return Value 

kDSTrue on success; kDSFalse on parameter error. kDSException means an 

exception, and the information about it can be found in errParams. 

Header File 

DigSigHFT.h 








5 

DigSigGetDocAuthorSignature 

CosObj DigSigGetDocAuthorSignature (PDDoc doc); 

Description 

Gets the author signature for a document as a Cos object. 

Parameters 

doc 

The document for which the author signature is obtained. 

Return Value 

The CosObj containing the author signature. 

Header File 

DigSigHFT.h 


DigSigGetDocMDPSetting 


5 



DSMDPType DigSigGetDocMDPSetting (PDDoc doc); 

Description 

Gets the MDP setting for the author signature for the specified document. 

Parameters 

doc 

The document for which the MDP setting is obtained. 

Return Value 

The MDP setting of the document’s author signature, or kDSMDPNone if there is no author 

signature. 

Header File 

DigSigHFT.h 





5 


CosObj DigSigGetStdXObj (CosDoc cosDoc,DSXObjType dsXObjType); 

Description 

Gets a Cos XObject for one of the standard signature graphics: blank, question mark, and 

cross. 

Creates an AcroForm dictionary if none exists in the document, makes a Default Resources 

(DR) dictionary if none exists, creates an XObject dictionary if none exists, and creates three 

standard XObjects: DSBlankXObj, DSUnknownXObj, and DSInvalidXObj if they do 

not exist. These objects may be used to modify the appearance of a digital signature. Each 

object has a bounding box of 100 x 100 points and an identity transformation matrix. 

Parameters 

cosDoc 

dsXObjType 


The type of object to get. 

Return Value 

Returns the CosObj of the desired type, or CosNewNull if unsuccessful. 

Header File 

DigSigHFT.h 


None 


5 


DigSigGetUbiquitySignature 

CosObj DigSigGetUbiquitySignature (PDDoc doc); 

Description 

Gets the Reader Extensions signature for a document as a Cos object. 

Parameters 

doc 

The document for which the Reader Extensions signature is obtained. 

Return Value 

The CosObj containing the Reader Extensions signature. 

Header File 

DigSigHFT.h 





5 

DigSigGetUniqueTitle 

char* DigSigGetUniqueTitle (CosDoc cosDoc); 

Description 

Gets a character string that is suitable as the field name for a new signature field. This is 

guaranteed not to duplicate an existing field name. Typically, this name would be of the 

form XXXXnnn, where XXXX is the word “signature” in a local Latin-alphabet language, and 

nnn is a unique integer. 

Parameters 

cosDoc 

The document that will contain the new field. 

Return Value 

The unique field name string. 

Header File 

DigSigHFT.h 


None 


5 



void DigSigHexToByte (unsigned char* hexP, 

unsigned char* byteP, ASInt32 length); 

Description 

Converts a PDF hex string to a byte string. For example, the 6-byte string converts 

to the 2-byte string (A/). 

The first byte of the hex string is ignored. The last byte of an even length hex string is 

ignored. 

Middle bytes outside the ranges 0-9, a-f, and A-F are treated as 0. Pairs of middle bytes are 

converted to byte values 0-255 and stored in the output buffer. 

Parameters 

hexP Pointer to the hex string. The string must begin with “”, 

optionally followed by a NULL character. 

byteP 

length 

(Filled by the method) Pointer to an output buffer to hold the byte string. 

Must be at least (length - 2) / 2 bytes long. 

Length of the hex string in bytes, not including any trailing NULL character, 

that is, strlen(hexP). 

Return Value 

None 

Header File 

DigSigHFT.h 


DigSigByteToHex 



5 

DigSigIsDocSigned 

ASBool DigSigIsDocSigned (PDDoc doc); 

Description 

Tests whether a document is signed. 

Parameters 

doc 

The document that is tested. 

Return Value 

true if the document is signed, false otherwise. 

Header File 

DigSigHFT.h 


DigSigIsSigSigned 


5 


DigSigIsSigSigned 

ASBool DigSigIsSigSigned (PDDoc doc, CosObj sigField); 

Description 

Tests whether a particular signature field in a document is signed. 

Parameters 

doc 

sigField 


The signature field that is tested. 

Return Value 

true if the signature field is signed, false otherwise. 

Header File 

DigSigHFT.h 


DigSigIsDocSigned 



5 

DigSigKeyDown 

void DigSigKeyDown (PDAnnot pdAnnot, AVPageView avpv, 

ASUns16 nKey, ASInt16 nFlags); 

Description 

The AcroForm plug-in calls this method when the user tabs to a signature annotation and 

activates it by pressing the spacebar or Enter key, which is equivalent to a left-mouse click. 

The parameters parallel those of the AVAnnotHandlerDoKeyDownProc callback. If the 

key pressed is an ASCII , this method selects the annotation. 

Parameters 

pdAnnot 

avpv 

nKey 

nFlags 

The annotation the user clicked on. 

The current page view. 

The key pressed by the user. 




● AV_OPTION 


● AV_SHIFT 

Return Value 

None 

Header File 

DigSigHFT.h 


DigSigDraw 

DigSigClick 



5 


DigSigMD5ByteRange 

ASInt32 DigSigMD5ByteRange (ASFile asFile, CosObj byteRange, 

char* md5hash); 

Description 

Calculates the MD5 hash function over a set of byte ranges in a file. 

Parameters 

asFile 

byteRange 

md5hash 

The file over which the hash function is calculated. 

An array of pairs of integers specifying byte offset and length of one or 

more subsets of the file. The hash function is calculated over all these 

subsets, concatenated in order. 

A pointer to a buffer that receives the 16-byte hash value. 

Return Value 

The MD-5 hash function over a set of byte ranges in asFile. Also returns the total number of 

bytes over which the hash is calculated. Returns 0 if the byte range array has an odd 

number of elements or if unsuccessful. 

Header File 

DigSigHFT.h 


None 



5 


DSRetCode DigSigNewSigRefDict (DSSigRefDictParams refParams, 

DSSigRefDictErrParams errParams); 

Description 

Begins the process of creating a new signature reference dictionary containing an object 

digest. The caller fills in the values of the refParams structure. 

In this method, no persistent changes are made to the document; therefore, it is safe to 

cancel the creation of the reference dictionary without any cleanup. To save the file, 

DigSigCommitSigRefDict should be called next. 

Parameters 

refParams 

errParams 

A structure containing information about the signature 

reference dictionary; must be filled in by the caller. 

(Filled by the method) A structure containing information 

about exceptions that occurred. 

Return Value 

kDSTrue on success; kDSFalse on parameter errors. 

kDSException means an exception occurred; information can be found in errParams. 

Header File 

DigSigHFT.h 







5 



ASInt32 DigSigOverwriteBytes (ASFile asFile, 

const DigSigOffset digSigOffset, const char* p); 

Description 

Overwrites any or all entries in a signature dictionary. Reopens the file for write, positions to 

the specified place, and writes exactly the number of bytes specified in digSigOffset. 

N OTE: 

To overwrite a text string entry, such as /Reason, the string must be in the format 

"< xxx >", not "xxx". 

Parameters 

asFile 

digSigOffset 

p 

The ASFile to write to. 

A structure specifying the byte position and size to overwrite. 

A byte string to be written. Must be in the correct format, given the 

type of entry as defined in Section 8.7 in the PDF Reference. 

Return Value 

The number of bytes written, or 0 if unsuccessful. 

Header File 

DigSigHFT.h 










5 


ASInt32 DigSigOverwriteHexstring (ASFile asFile, 

const DigSigOffset digSigOffset, const CosObj cosObj); 

Description 

Overwrites part of a file with a hex string. Reopens the file for write, positions to the 

specified location, formats the string as characters, and writes. This method is used to 

overwrite the /Contents entry in the signature dictionary. 

Parameters 

asFile 

digSigOffset 

cosObj 



● Writes padding blanks to the file if formatted length is less than 

this length. 

● Does not write and returns 0 if the formatted length is longer than 

this length. 

● Does not write and returns 0 if the formatted length is greater 

than 8200 bytes. 

The Cos string to be written. 

Return Value 

The number of bytes written. 

Header File 

DigSigHFT.h 









5 



ASInt32 DigSigOverwriteIntArray (ASFile asFile, 

const DigSigOffset digSigOffset, const CosObj cosObj); 

Description 

Overwrites part of asFile with an integer array. Reopens the file for write, positions to the 

specified place, formats the array as characters, and writes. This method is used to 

overwrite the /ByteRange entry in the signature dictionary. 

Parameters 

asFile 

digSigOffset 

cosObj 



● Writes padding blanks to the file if formatted length is less than 

this length. 

● Does not write and returns 0 if the formatted length is longer 

than this length. 

● Does not write and returns 0 if the formatted length is greater 

than 8200 bytes. 

The Cos string to be written. 

Return Value 

The number of bytes written. 

Header File 

DigSigHFT.h 










5 

DigSigRegisterFilter 

void DigSigRegisterFilter (ExtensionID owner, 

DigSigHandler digSigHandler); 

Description 

Registers a signing method plug-in. A signing plug-in must call this method before making 

any signatures. This object should not be destroyed until after it is unregistered or until exit. 

Parameters 

owner 

digSigHandler 

The handler plug-in identifier, assigned on initialization. 

A structure specifying the name of the filter and the functions to 

call to create and validate signatures. 

Return Value 

None 

Header File 

DigSigHFT.h 


DigSigUnregisterFilter 


5 


DigSigRegisterObserver 

ASInt32 DigSigRegisterObserver 

(DSNotificationType notificationID, 

DSNotificationProc notifyProc, 

DSNotificationFailureProc notifyFailure, void *clientData); 

Description 

Registers callbacks with the notification server, to be called for specific digital signature 

events. Events are: 

● Adding or deleting a signature field. 

● Requesting a new signature, and the success or failure of the request. 

● Requesting that an existing signature be cleared, and the success or failure of the 

request. 

Parameters 

notificationID 

notifyProc 

notifyFailure 

clientData 

The type of event for which to register a callback. 

The procedure to call when a field change, request, or success 

event occurs. 

The procedure to call when a failure event occurs. 

A pointer to client-supplied data to pass to the callback 

procedure. 

Return Value 

The observer identifier, which must be provided to DigSigUnregisterObserver. 

Header File 

DigSigHFT.h 


DigSigUnregisterObserver 



5 


void DigSigRightClick (PDAnnot pdAnnot, AVPageView avPV, 

ASInt16 nX, ASInt16 nY, ASInt16 nFlags, ASInt16 nClicks); 

Description 

Invokes the signature-panel pull-right menu and allows the user to select an action. 

Parameters 

pdAnnot 

avPV 

nX 

nY 

nFlags 

nClicks 

The annotation the user clicked on. 

The page view the annotation is within. 

The x-coordinate of the mouse click, specified in device space coordinates. 

The y-coordinate of the mouse click, specified in device space coordinates 




● AV_OPTION 


● AV_SHIFT 

The number of clicks. 

Return Value 

None 

Header File 

DigSigHFT.h 


DigSigDraw 


DigSigClick 


5 


DigSigRollbackToSig 

void DigSigRollbackToSig (PDDoc pdDoc, CosObj sigField); 

Description 

Creates a new temporary file that corresponds to the state of the file after the specified 

signature was applied. 

Parameters 

pdDoc 

sigField 


The signature field of the document. 

Return Value 

None 

Header File 

DigSigHFT.h 


None 



5 

DigSigSignDoc 

void DigSigSignDoc (PDDoc pdDoc, CosObj sigField, 

ASAtom filterKey); 

Description 

Signs and saves a document, using the specified field and signing method. If sigField is 

NULL, makes a field of size 0x0 points. 

Parameters 

pdDoc 

sigField 

filtrKey 

The document to be signed. 

The field to be signed or CosNull. 

The signing method to use. 

Return Value 

None 

Header File 

DigSigHFT.h 


None 


5 


DigSigUnregisterFilter 

void DigSigUnregisterFilter (DigSigHandler digSigHandler); 

Description 

Unregisters a signing method plug-in. The caller should deallocate the DigSigHandler 

object after making this call. 

Parameters 

digSigHandler 

A structure specifying the name of the filter and the functions to 

call to create and validate signatures. 

Return Value 

None 

Header File 

DigSigHFT.h 





5 

DigSigUnregisterObserver 

void DigSigUnregisterObserver 

(DSNotificationType notificationID, ASInt32 observerID); 

Description 

Unregisters an event interest from the notification server. 

Parameters 


observerID 

The event for which an interest has been registered, as specified 

in DigSigRegisterObserver. 

The observer identifier as returned by 

DigSigRegisterObserver. 

Return Value 

None 

Header File 

DigSigHFT.h 




5 


DigSigUpdatePanel 

void DigSigUpdatePanel (PDDoc pdDoc); 

Description 

Updates the signature panel, if any, associated with pdDoc. 

Parameters 

pdDoc 

The document whose panel is to be updated. 

Return Value 

None 

Header File 

DigSigHFT.h 


None 



5 


DSValidState DigSigVerifySig (PDDoc pdDoc, CosObj sigField, 

ASBool bUI); 

Description 

Verifies a digital signature. 

Parameters 

pdDoc 

sigField 

bUI 

The document. 

The signature field to verify. 

When true, can bring up the user-interface dialogs if needed. 

Return Value 

The validity state that results from verification. 

Header File 

DigSigHFT.h 


DigSigClearSig 


5 



DSRetCode DigSigVerifySigRefDict (ASAtom transformMethod, 

CosObj sigDict, CosObj refDict, 

DSSigRefDictErrParams errParams ); 

Description 

Verifies an object signature stored in a signature reference dictionary. It involves computing 

the object digest using the transform method and comparing it to the digest value stored 

in the reference dictionary. 

Parameters 


The transform method used to calculate the signature. It must 

match the one stored in refDict 

sigDict The signature dictionary that contains the signature 


refDict 

errParams 

The signature reference dictionary that was returned from a 

call to DigSigCommitSigRefDict 

A structure containing information about an exception. 

Return Value 

kDSTrue on success; kDSFalse on parameter error. kDSException means an 

exception, and the information about it can be found in errParams. 

Header File 

DigSigHFT.h 







6 

Digital Signature Callbacks 

DigSigEnumProc 

ACCB1 ASBool ACCB2 DigSigEnumProc (PDDoc pdDoc, 

CosObj sigField, void *clientdata); 

Description 

User-supplied callback that is passed in the call to DigSigEnumSignatures. DigSig 

calls this once for each existing signature. 

Parameters 

pdDoc 

sigField 

clientData 




Return Value 

true to continue enumeration, false otherwise. 

Header File 

DigSigHFT.h 


DigSigEnumSignatures 


6 


DSCanValidateProc 

ACCB1 ASBool(ACCB2 *DSCanValidateProc) 

(PDDoc pdDoc, CosObj sigField, CosObj sigAnnot, 

ASAtom filter); 

Description 

This function is called to query the handler to find out if it can validate this PDDoc 

signature field. The call determines if the general signature format is supported by the 

handler, or if the handler should be given the opportunity to validate this signature. 

If the response is false, the handler cannot be called to validate the signature. In this 

event, the handler will not be able to provide other information (for example that an 

updated version of the handler should be obtained in order to validate the signature). 

Parameters 

pdDoc 

sigField 

sigAnnot 

filter 



The signature annotation that is being verified (usually equivalent to 

sigField). 

The name by which DigSig knows this handler. This is not necessarily 

the value of /Filter. 

Return Value 

true if the handler can validate the field signature, false otherwise. 

Header File 

DigSigHFT.h 





6 

DSClearSigProc 

void DSClearSigProc (PDDoc pdDoc, CosObj sigField, 

CosObj sigAnnot); 

Description 

DigSig uses this callback to send notification that it has cleared the signature. This clears 

the local caching. 

Parameters 

pdDoc 

sigField 

sigAnnot 

The document being signed. 

Signature field. 

Cos object of the signature annotation. 

Return Value 

None. 

Header File 

DigSigHFT.h 


6 


DSCommitSignProc 

ACCB1 ASBool ACCB2 DSCommitSignProc (PDDoc pdDoc, 

void* sigData, CosObj sigField, CosObj sigAnnot, 

DigSigOffset* offsetArray, ASInt32* arrayCount); 

Description 

Callback for DigSigHandler. Called to put signature into document in memory or to 

cancel. Modifies the signature dictionary as needed. May allocate storage for an array of 

signature objects. 

The signature includes a signature dictionary written to the /V attribute of the sigField 

and an optional appearance written to the /AP dictionary of the sigAnnot. 

See Section 8.7 in the PDF Reference for the format of the signature dictionary. At least two 

objects in the signature dictionary, ByteRange and Contents, will need to be overwritten 

during the DSFinishSignProc callback. 

Parameters 

pdDoc 

sigData 

sigField 

sigAnnot 

offsetArray 


Signature data, as defined by the specific signature plug-in. 



(Optional) An offset array pointing to a set of “marked” Cos objects 

that the signature type cares about; this array includes at least the 

ByteRange and Contents value objects. 

arrayCount 

(Optional) Number of objects in offsetArray, if used 

Return Value 

true if the signature was successfully placed in pdDoc, false otherwise. 

Header File 

DigSigHFT.h 


DSFinishSignProc 

DSNewSigDataProc 



6 

DSDefaultValueProc 

Description 

Parameters 

ACCB1 void ACCB2 DSDefaultValueProc (PDDoc pdDoc, 

CosObj sigField, CosObj sigAnnot); 

N OTE: Deprecated in Acrobat 6.0. 

Callback for DigSigHandler. Called when a new signature field is created. This method 

creates the default signature value dictionary and creates a default value (DV) entry in the 

signature field dictionary pointing to this dictionary. 

pdDoc 

sigField 

sigAnnot 




Return Value 

None 

Header File 

DigSigHFT.h 


6 


DSDocCloseProc 

ACCB1 void ACCB2 DSDocCloseProc (PDDoc pdDoc); 

Description 

Callback for DigSigHandler. Called when a new document is closed. 

Parameters 

pdDoc 

The document being closed. 

Return Value 

None 

Header File 

DigSigHFT.h 


DSDocOpenProc 



6 

DSDocOpenProc 

ACCB1 void ACCB2* DSDocOpenProc (PDDoc pdDoc); 

Description 

Callback for DigSigHandler. Called when a new document is opened. 

Parameters 

pdDoc 

The document that has been opened. 

Return Value 

None 

Header File 

DigSigHFT.h 


DSDocCloseProc 


6 



ACCB1 ASBool ACCB2 DSFinishSignProc (PDDoc pdDoc, 

void* sigData, CosObj sigField, CosObj sigAnnot, 

DigSigOffset offsetArray, ASInt32 arrayCount); 

Description 

Callback for DigSigHandler. Called to calculate checksum and update disk copy of 

document. May use information from the offsetArray parameter. 

Parameters 

pdDoc 

sigData 

sigField 

sigAnnot 

offsetArray 

arrayCount 





(Optional) An offset array pointing to a set of “marked” Cos objects 

that the signature type cares about; this array includes at least the 

ByteRange and Contents value objects. 

(Optional) Number of objects in offsetArray, if used 

Return Value 

true if processing successful, false otherwise. 

Header File 

DigSigHFT.h 








6 

DSFreeSigDataProc 

ACCB1 void ACCB2 DSFreeSigDataProc (void* sigData); 

Description 

Callback for DigSigHandler. Frees signature data. 

Parameters 

sigData 

Signature data, as defined by the specific signature plug-in. The handler 

should check to see if sigData is NULL. 

Return Value 

None 

Header File 

DigSigHFT.h 


6 


DSGetBoolPropertyProc 

ACCB1 ASBool (ACCB2 *DSGetBoolPropertyProc) 

(ASAtom filter, DSHandlerProperty property); 

Description 

Get the boolean value of a DigSig handler property. Return true for those properties that 

represent functionality your handler supports, false if it does not support the 

functionality. (Some properties are available directly from the DigSigHandler.) 

Parameters 

filter 

property 

The name (filterKey value) of the handler from which the property is 

obtained. 

The property whose value is obtained. 

Return Value 

The property value, true or false. 

Header File 

DigSigHFT.h 



6 

DSGetSigPropProc 

ACCB1 ASCab (ACCB2 *DSGetSigPropProc) 

(PDDoc pdDoc, CosObj sigField, CosObj sigAnnot, 

ASAtom handlerName); 

Description 

Called to obtain an ASCab containing values that the handler wants DigSig to use in the UI. 

This is called only after the handler is called to validate the signature. 

Parameters 

pdDoc 

sigField 

sigAnnot 

handlerName 




The name of the handler that is being asked to return the data. This 

is not necessarly the same as the value of the /Filter attribute in the 

signature dictionary. 

Return Value 

An ASCab object containing the properties. For a list of properties, see DigSigHFT.h. 

Header File 

DigSigHFT.h 


6 


DSGetStatusTextProc 

ASText DSGetStatusTextProc (PDDoc pdDoc, CosObj sigField, 


Description 

Return a string describing the status of the signature. Must be PDDocEncoding or 

unicode, where unicode strings must start with 0xFE, 0xFF. 

N OTE: 

Superceded by DSGetSigPropProc in Acrobat 6.0, which provides better 

granularity for signature status. 

Parameters 

pdDoc 

sigField 

sigAnnot 




Return Value 

None. 

Header File 

DigSigHFT.h 



6 

DSGetValidStateProc 

ACCB1 DSValidState ACCB2 DSGetValidStateProc (PDDoc pdDoc, 


Description 

Callback for DigSigHandler. Called by signature panel display to choose which of the 

double-checked, pass, fail, unknown, or blank icons to show. May call 

DigSigUpdatePanel to update the signature panel. 

Parameters 

pdDoc 

sigField 

sigAnnot 




Enumerations 

DSSigBlank 

DSSigUnknown 

DSSigInValid 

DSSigValid 

DSSigDoubleChecked 

The signature field is unsigned. 

The signature field is signed but not validated. 

The signature field is signed but invalid. 

The signature field is signed and valid. 

The signature field is signed and double-checked valid. 

Return Value 

Validation state. 

Header File 

DigSigHFT.h 




6 



Description 

Parameters 

ACCB1 ASBool ACCB2 DSNewSigDataProc (PDDoc pdDoc, 

DigSigBBox bb, void** sigData, CosObj sigField, 


N OTE: Superceded in Acrobat 6.0 by DSNewSigDataWithParamsProc. 

Callback for DigSigHandler. Called to gather signature data or to cancel. May display 

dialogs. May use the default value (DV) field of the signature field if it is not CosNull. 

To allow for a user to cancel signing, the handler should not modify the document during 

this callback. The handler will commit the signature to the PDF file during 

DSClearSigProc. 

pdDoc 

bb 

sigData 

sigField 

sigAnnot 


Signature annotation bounding box. 




Return Value 

true if signature data gathered, false if canceled. 

Header File 

DigSigHFT.h 








6 


Description 

Parameters 

ACCB1 DSSaveType ACCB2 DSNewSigDataProc 

(DigSigNewSigDataParams sigParams, void** sigData); 

N OTE: Supercedes DSNewSigDataProc in Acrobat 6.0. 

Callback for DigSigHandler. Creates new signature data to be used by Commit and 

Finish, then destroyed by DSFreeSigDataProc. 

If a dialog is not used (bUI in parameters is false) then exception strings are stored in the 

signature data, and can be retrieved with DSSigDataGetErrorTextProc. 

sigParams 

sigData 

The structure containing signing parameters. 

(Filled by the method) Signature data, as defined by the specific 

signature plug-in. 

Return Value 

A constant indicating the action to be performed on the document; cancel signing, save to 

the same filename, or save to a new filename. 

Header File 

DigSigHFT.h 


DSCommitSignProc 




DSSigDataGetErrorTextProc 


6 


DSNotificationProc 

ACCB1 void (ACCB2 *DSNotificationProc)(void *info, 

void *clientData); 

Description 

Callback for the Notification Server. Called when a digital signature event occurs for which 

you have registered an interest. This procedure is called for these events: 

● Adding or deleting a signature field. 

● Requesting a new signature, and the success of the request. 

● Requesting that an existing signature be cleared, and the success of the request. 

For failure events, the server calls the DSNotificationFailureProc. 

Parameters 

info 

clientData 

Pointer to a DSNotifyParams structure containing information 

about the event. 


Return Value 

None 

Header File 

DigSigHFT.h 


DSNotificationFailureProc 





6 


ACCB1 void (ACCB2 *DSNotificationFailureProc)(ASInt32 error, 

void *info, void *clientData); 

Description 

Callback for the Notification Server. Called when a digital signature event occurs for which 

you have registered an interest. This procedure is called for these events: 

● The failure of a request for a new signature. 

● The failure of a request for an existing signatureto be cleared. 

For field change, request, and success events, the server calls the 

DSNotificationProc. 

Parameters 

error 

info 

clientData 

The error code for the error that occured. 

Pointer to a DSNotifyParams structure containing information 

about the event. 


Return Value 

None 

Header File 

DigSigHFT.h 






6 


DSPropertiesProc 

Description 

Parameters 

ACCB1 void ACCB2 DSPropertiesProc (PDDoc pdDoc, 


N OTE: Superceded by DSPropertiesExProc in Acrobat 6.0. 

Callback for DigSigHandler. Called when a user selects a signature and asks for its 

properties. The handler should present its own dialog that provides details concerning the 

signature and its validation state. 

pdDoc 

sigField 

sigAnnot 




Return Value 

None 

Header File 

DigSigHFT.h 





6 

DSPropertiesExProc 

Description 

Parameters 

ACCB1 void ACCB2 DSPropertiesExProc (PDDoc pdDoc, 

CosObj sigField, CosObj sigAnnot, ASAtom handlerName, 

ESObject sigEngine); 

N OTE: Supercedes DSPropertiesProc in Acrobat 6.0. 

Callback for DigSigHandler. Called when a user selects a signature and asks for its 

properties. Brings up the properties dialog for the signature. 

pdDoc 

sigField 

sigAnnot 

handlerName 

sigEngine 




The sub-handler to use to validate, in the event that the handler has 

more then one sub-handler (as is the case with PubSec), and the 

handler is being asked to validate a signature that has a different 

filter name then its own. 


Return Value 

None 

Header File 

DigSigHFT.h 




6 


DSReValidateSigProc 

ACCB1 void ACCB2 DSReValidateSigProc (PDDoc pdDoc, 


Description 

Callback for DigSigHandler. Acrobat will call this to optionally change appearance key 

(AP) back to the state it had just before the prior call (if any) to DSUnValidateSigProc. 

Call DSUnValidateSigProc on every signature field just before saving a document and 

call DSReValidateSigProc just after. The intended effect is that saved documents 

always have signed signature appearances of unknown validity (question mark), but that 

saving does not necessarily change the onscreen appearance of validated signatures. 

Parameters 

pdDoc 

sigField 

sigAnnot 




Return Value 

None 

Header File 

DigSigHFT.h 


DSUnValidateSigProc 



6 

DSSigDataGetErrorTextProc 

ACCB1 ASText (ACCB2 *DSSigDataGetErrorTextProc) 

(void *sigData); 

Description 

Returns an error string to describe failure during new, commit, or free steps. If not NULL, 

then a JavaScript general exception is thrown using this string. 

The handler can set this procedure to NULL if desired. 

The string is owned by sigData, so should be freed by DSFreeSigDataProc. 

Parameters 

sigData 

A pointer to the signature for which the error string is obtained. 

Return Value 

The error string as an ASText. 

Header File 

DigSigHFT.h 





6 



ACCB1 void ACCB2 DSUnValidateSigProc (PDDoc pdDoc, 

CosObj sigField, CosDoc sigAnnot); 

Description 

Callback for DigSigHandler. Called to change appearance key (AP) back to appearance 

that is used for the unvalidated state. 

Parameters 

pdDoc 

sigField 

sigAnnot 




Return Value 

None 

Header File 

DigSigHFT.h 


DSValidateSigProc 











6 


ACCB1 DSValidState ACCB2 DSValidateSigProc (PDDoc pdDoc, 


Description 

Callback for DigSigHandler. Called to validate a signature. Recalculates any document 

digest that it desires, possibly using the DigSigFileGetEOF, DigSigMD5ByteRange, 

DigSigFileRead, and DigSigFileSetPos methods. 

May compare this result to the stored one, and do any other signature-specific checks 

desired. Optionally does a validation against a stored (network) registry. If necessary, 

updates the AP dictionary in the signature annotation dictionary to show the validation 

state of the signature. 

Parameters 

pdDoc 

sigField 

sigAnnot 




Return Value 

Validation state. 

Header File 

DigSigHFT.h 










6 




6 


6 



7 

Digital Signature Declarations 

DigSigBBox 

typedef struct _t_DigSigBBoxRec* DigSigBBox; 

typedef struct _t_DigSigBBoxRec 

{ 

Fixed bbWidth; 

Fixed bbHeight; 

} 

DigSigBBoxRec; 

Description 

Signature annotation bounding box. 

Members 

bbwidth 

bbHeight 

The width of the signature bounding box. 

The height of the signature bounding box. 

Header File 

DigSigHFT.h 




7 


DigSigHandler 

typedef struct _t_DigSigHandlerRec* DigSigHandler; 

typedef struct _t_DigSigHandlerRec 

{ 


const char* uiName; 

ASAtom filterKey; 

ASBool canBlindSign; 

ASBool canEncrypt; 

DSDocOpenProc dsDocOpen; 

DSDocCloseProc dsDocClose; 

DSDefaultValueProc dsDefaultValue; 

DSNewSigDataProc dsNewSigData; 

DSClearSigProc dsCommitSign; 

DSFinishSignProc dsFinishSign; 

DSFreeSigDataProc dsFreeSigData; */ 

DSValidateSigProc dsValidateSig; 

DSGetValidStateProc dsGetValidState; 

DSPropertiesProc dsProperties; 

DSUnValidateSigProc dsUnValidateSig; 

DSReValidateSigProc dsReValidateSig; 

/* New in Acrobat 5.0 */ 

DSClearSigProc dsClearSig; 

DSGetStatusTextProc dsStatusText; 

DSNewSigDataExProc dsNewSigDataEx; /* internal */ 

DSValidateSigExProc dsValidateSigEx; /* internal */ 

DSGetSigInfoProc dsGetSigInfo; /* internal */ 

DSNewSigEngineProc dsNewSigEngine; /* not used */ 

DSSigDataGetErrorTextProc dsSigDataGetErrorText; 

/* New in Acrobat 6.0 */ 

DSNewSigDataWithParamsProc dsNewSigDataWithParams; 

DSPropertiesExProc dsPropertiesEx; 

DSCosDocSigSignProc dsCosDocSigSign; /*internal*/ 

DSCosDocSigValidateProc dsCosDocSigValidate; /*internal*/ 

DSDataBufferSigSignProc dsDataBufferSigSign;/*internal*/ 

DSDataBufferSigValidateProc dsDataBufferSigValidate; 

/*internal*/ 

DSCanValidateProc dsCanValidate; 

DSGetSigSeedValueProc dsGetSigSeedValue; /* internal */ 

DSSetSigSeedValueProc dsSetSigSeedValue; /* internal */ 

DSGetBoolPropertyProc dsGetBoolProperty; 

DSGetSigPropProc dsGetSigProp; 

} 

DigSigHandlerRec; 

Description 

Data structure containing callbacks that define a signature plug-in’s behavior. 



7 

Members 

size 

uiName 

filterKey 

canBindSign 

canEncrypt 

dsDocOpen 

dsDocClose 

Size of the data structure. Must be set to 

sizeof(DigSigHandlerRec). 

Language-dependent name to show for signature 

type selection. 

The value of the Filter key in the signature 

dictionary. 

true if this signature type can do no-appearance 

signatures, false otherwise. 

true if this signature type can do encrypt-and-sign, 


Called when a new document is opened. 

Called when a new document is closed. 

dsDefaultValue Called when a new signature field is created. 

dsNewSigData 

dsCommitSign 

dsFinishSign 

dsFreeSigData 

dsGetValidState 

dsProperties 

dsUnValidateSig 

dsReValidateSig 

dsClearSig 

dsStatusText 

dsNewSigDataEx 

dsValidateSigEx 

dsGetSigInfo 

dsNewSigEngine 

Called to gather signature or cancel. 

Called to put signature into doc or cancel. 

Called to calculate checksum and overwrite. 

Called to free signature data. 

Called by sig panel display. 

Called by sig panel display. 

Called to change AP back to unvalidated. 

Called to change AP back to whatever it was. 

Notification that signature has been cleared. 

Called to get a string describing status. 

Used internally in Acrobat 5.0. Superceded in 

Acrobat 6.0 by dsNewSigDataWithParams. 

Used internally by PubSec. 

Used internally by EScript in Acrobat 5.0. No longer 

used. 


7 


dsSigDataGetErrorText 

dsNewSigDataWithParams 

dsPropertiesEx 

dsCosDocSigSign 

dsCosDocSigValidate 

dsDataBufferSigSign 

dsDataBufferSigValidate 

dsCanValidate 

dsGetSigSeedValue 

dsSetSigSeedValue 

dsGetBoolProperty 

dsGetSigProp 

Called to get a descriptive string for an error during 

new, commit, or free steps. 

Called to create new signature data to be used by 

Commit and Finish. Supercedes ds 

Called to show the signature properties dialog for 

the signature. 

For internal use only. 

Called to determine whether handler can validate a 

PDDoc field signature. 

Used internally by PubSec. 

Called to test whether your handler supports specific 

functionality. 

Called to get an ASCab containing signature 

properties to be used in the UI. 

Header File 

DigSigHFT.h 





7 

DigSigNewSigDataParams 

typedef struct _t_DigSigNewSigDataParamsRec { 


PDDoc pdDoc; 


CosObj sigAnnot; 

DigSigBBox bb; 

ASAtom filter; 

ESObject esSigEngine; /*internal*/ 

ESObject esSigParams; /*internal*/ 

ASText esErrorText; 

ASBool bUI; 

ASBool bDocAuthSig; 

CosObj legalPDFDict; 

DSMDPType mdpSetting; 

} DigSigNewSigDataParamsRec, *DigSigNewSigDataParams; 

Description 

Parameters for DSNewSigDataWithParamsProc. 

Members 

size 

pdDoc 

sigField 

sigAnnot 

bb 

filter 

esSigEngine 

esSigParams 

esErrorText 

bUI 

bDocAuthSig 


sizeof(DigSigNewSigDataParamsRec). 

The PDF document that is being signed. 

Signature form field that is being signed. 

Signature annotation that is being signed (usually equivalent to 

sigField). 

Bounding box of signature appearance. 

Name of the selected handler to use when signing. 


If true, prompt to sign, otherwise silent. (Can be true with 

Escript.) 

When true, signing a document author signature. 


7 


legalPDFDict 

mdpSetting 

Legal PDF scrubber warnings, populated only when signing a 

document author signature. 

Modification, detection, and prevention (MDP) setting, populated 

only when signing a document author signature. One of: 

● kDSMDPAllowAll: Allow all changes (disables MDP). 

● kDSMDPAllowNone: Allow no changes. 

● kDSMDPDefault: Allow only "natural" changes (form-field 

filling, page spawning). 

● kDSMDPCommentsAndDefault: Allow all comment types 

edit/modify/delete, in addition to default changes. 

Header File 

DigSigHFT.h 





7 

DigSigOffset 

DigSigOffsetRec 

typedef struct _t_DigSigOffsetRec* DigSigOffset; 

typedef struct _t_DigSigOffsetRec 

{ 

CosObj cosObj; 

ASInt32 byteOffset; 

ASInt32 byteLength; 

} 

DigSigOffsetRec; 

Description 

Structure that indicates the location of objects in a saved PDF document. 

Members 

cosObj 

byteOffset 

byteLength 

The CosObj whose byte offset/length is desired. 

Byte offset in saved PDF file. 

Length in saved PDF file. 

Header File 

DigSigHFT.h 










7 


DSAPCreateLayeredStreamExParams 

typedef struct _t_DSAPCreateLayeredStreamExParams 

{ 


CosObj* XObjects; 

ASFixedMatrixP layerMatrices; 

ASInt32 numXObjects; 

ASInt16 layerNNum; 

AFPDWidgetBorder border; 

PDColorValue cBorder; 

PDColorValue cBackGnd; 

ASFixed width; 

ASFixed height; 

PDRotate pdr; 

ASBool* layerFlags; 

} DSAPCreateLayeredStreamExParamsRec, 

*DSAPCreateLayeredStreamExParams; 

Description 

Parameter structure for DigSigAPCreateLayeredStreamEx, that creates a stream 

that is composed of either four or five layers, as specified by layerMatrices: 

● layer 0: background, inherited from form annot background 

● layer 1: middle, question mark or equivalent (uses the default if the corresponding 

XObject is CosNull) 

● layer 2: main, text and appearance (must be provided) 

● layer 3: top, blank or X (uses the default if the layer1 XObject is CosNull) 

● layer N: optional very top layer, used for text showing validity state (none if CosNull) 

Members 

cosDoc 

XObjects 

layerMatrices 

numXObjects 

layerNNum 

border 


A pointer to an array of XObjects for the appearance layers. 

A pointer to an array of positions corresponding to the layers in 

XObjects. 

The size of the XObjects array. 

The layer number for the optional validity state layer. 

The border from AFPDWidgetGetBorder. 



7 

cBorder 

cBackGnd 

width 

height 

pdr 

layerFlags 

The color of the border. 

color of the background. 

The width of the new stream object. 

The height of the new stream object. 

The rotational parameter from AFPDWidgerGetRotation. 

An array of flag values corresponding to the layers specified by 

XObject. A value of true means that the corresponding layer is 

displayed. 


7 


DSAPTextEntry 

typedef struct _t_DSAPTextEntryRec { 

struct _t_DSAPTextEntryRec *next; 

ASFixed heightRatio; 

ASText text; 

} DSAPTextEntryRec, *DSAPTextEntry; 

Description 

A linked list of text items to be merged together in a signature appearance XObject. 

Members 

next 

heightRation 

text 

Next list entry, or NULL if last entry. 

Ration of the text height to the overall height of the bounding box. 

0x00010000 is 100% 

The text to render in this object. The caller owns this memory. 

Header File 

DigSigHFT.h 





7 

DSAPXObjEntry 

DSAPXObjEntryRec 

typedef struct _t_DSAPXObjEntryRec{ 

struct _t_DSAPXObjEntryRec * next; 

CosObj xobj; 

ASFixedRect rect; 

const char* text; 

ASInt 32 textLen; 

ASFixed textSize; 

DSQuadding xjustify; 

DSQuadding yjustify; 

ASFixed scale; 

ASBool bMerge; 

ASBool bDestroy; 

} DSAPXObjEntryRec, *DSAPXObjEntry; 

Description 

Structure used in DigSigAPXObjectFromXObjList. 

Members 

next 

xobj 

rect 

text 

textLen 

textSize 

xjustify 

yjustify 

scale 

bMerge 

bDestroy 

Next list entry. 

If not null, use this Xobject as entry. 

Rect relative to bbox in which to render object. 

If not empty, render this string (can contain new lines). 

Text length. 

Font size; 0 for automatic. 

Justification of xobj (not all options supported). 

Justification of xobj (not all options supported). 

Scale Xobject within rect. 

If true and xobj is Subtype Xobject then xobj is merged up. 

if true, destroy xobj after merge. 


7 


Header File 

DigSigHFT.h 





7 

DSComparePagesParams 

typedef struct _t_DSComparePagesParamsRec { 


ASInt32 sensitivityLevel; 

} DSComparePagesParamsRec, *DSComparePagesParams; 

Description 

Parameters for page comparison. 

Members 

size 

sensitivityLevel 


sizeof(DSComparePagesParamsRec). 

The sensitivity level for the comparison. The DPI determines 

the resolution at which each page is rendered before 

comparing on a pixel-by-pixel basis. Values are: 

0: 72 DPI 

1: 36 DPI 

2: 18 DPI 

Header File 

DigSigHFT.h 




7 


DSCompareWordsParams 

typedef struct _t_DSCompareWordsParamsRec { 


ASBool useFont; 

} DSCompareWordsParamsRec, *DSCompareWordsParams; 

Description 

Parameters for page comparison. 

Members 

size 

useFont 


sizeof(DSCompareWordsParamsRec). 




Header File 

DigSigHFT.h 





7 

DSHandlerProperty 


kDSHandlerCanDocAuthSign=0, 

kDSHandlerCanDocPDDocSignVisible, 

kDSHandlerEScriptAware, 

kDSHandlerPropEnumSize 

} DSHandlerProperty; 

Description 

Boolean properties of a DigSigHandler, obtained with DSGetBoolPropertyProc, 

that show whether the handler supports specific functionality. 

Values 

kDSHandlerCanDocAuthSign 

kDSHandlerCanDocPDDocSignVisible 

kDSHandlerEScriptAware 

When true, the handler supports 

author signatures. 


ordinary visible signatures. 


EScript. 


DSGetBoolPropertyProc 


7 


DSMDPType 


kDSMDPNone = -1, 

kDSMDPAllowAll=0, 

kDSMDPAllowNone, 

kDSMDPDefault, 

kDSMDPCommentsAndDefault, 

kDSMDPEnumSize 

} DSMDPType; 

Description 

The modification detection and prevention (MDP) value for an author signature. 

Members 

kDSMDPNone 

kDSMDPAllowAll 

kDSMDPAllowNone 

kDSMDPDefault 

kDSMDPCommentsAndDefault 

No MDP, or the document does not have an author 

signature. 

Allow any changes (this disables the MDP feature). 

Allow no changes. 

Only allow 'natural' changes ( form field fill-in, 

page spawning). 

Allow all comment types, edit, modify, and delete 

operationa, in addition to default changes. 

Header File 

DigSigHFT.h 





7 

DSNotificationType 


DSSigAdded = 0, 

DSSigDeleted, 

DSWillSign, 

DSDidSign, 

DSFailSign, 

DSWillVerify, /*new in Acrobat 6.0*/ 

DSDidVerify, /*new in Acrobat 6.0*/ 

DSFailVerify, /*new in Acrobat 6.0*/ 

DSWillClear, 

DSDidClear, 

DSFailClear, 

DigSigNumNotifications 

} DSNotificationType; 

Description 

A type of notification to register for. 

Members 

DSSigAdded 

DSSigDeleted 

DSWillSign 

DSDidSign 

DSFailSign 

DSWillVerify 

DSDidVerify 

DSFailVerify 

DSWillClear 

DSDidClear 

DSFailClear 

Signature field is added. 

Signature field is deleted. 

A signature is requested. (That is, the notification procedure is 

invoked before the signature is applied.) 

A signature is created. (That is, the notification procedure is 

invoked when signing succeeds.) 

A signature request fails. (That is, the notification procedure is 

invoked when signing fails.) 

A signature verification is requested. 

A signature verification succeeds. 

A signature verification request fails. 

The clearing of a signature is requested. 

The clearing of a signature succeeds. 

The clearing of a signature fails. 


7 


Header File 

DigSigHFT.h 





7 

DSNotifyParams 

typedef struct _t_DSNtfyParamsRec { 


DSNotificationType notificationID; 

PDDoc pdDoc; 




} DSNtfyParamsRec, *DSNtfyParams; 

Description 

A structure passed to the callback when a digital signature event occurs for which an 

interest has been registered. The structure contains information about the event. 

Members 

size 


pdDoc 

cosDoc 

sigField 

sigDict 


sizeof(DSNotifyParamsRec). 

The event that occurred. 

The PDF document for which the event occurred. 

The Cos document containing the object for which the event 

occurred. 

The signature field for which the event occurred. 

The signature dictionary (used only for the events DSDidSign 

and DSDidClear). 

Header File 

DigSigHFT.h 







7 


DSOverwriteType 


DSOverwriteStringHex=0, 

DSOverwriteStringBase64, 

DSOverwriteArray, 

DSOverwriteEnumSize 

} DSOverwriteType; 

Description 

Constant values that determine the type of Cos object overwrite to be performed. 

Members 

DSOverwriteStringHex Overwrite a hex-encoded CosString that uses < 

and > delimiters. 

DSOverwriteStringBase64 

Overwrite a base64-encoded CosString that 

uses ( and ) delimiters. All non-base64 characters in 

the overwrite string are ignored. 

DSOverwriteArray Overwrite a CosArray . 

Header File 

DigSigHFT.h 





7 

DSQuadding 


DSLeftQ = 0, 

DSCenterQ, 

DSRightQ 

} DSQuadding; 

Description 

Justification of XObjects. 

Members 

DSLeftQ 

DSCenterQ 

DSRightQ 

left justification. 

center justification 

right justification 

Header File 

DigSigHFT.h 




7 


DSSigRefDictErrParams 

typedef struct _t_DSSigRefDictErrParamsRec { 


DSSigRefErrCode errCode; 

ASText errText; 

} DSSigRefDictErrParamsRec, *DSSigRefDictErrParams; 

Description 

A structure that contains information about exceptions that occurred in signature reference 

dictionary procedures. 

Members 

size 

errCode 

errText 

The size of this structure. 

The exception code. 

Text associated with the error code. If errCode is 

kDSSigRefErrMissingPlugin, the name of a software module. 

Must point to an initialized ASText object. 

Header File 


DigSigHFT.h 






7 

DSSigRefDictParams 

typedef struct _t_DSSigRefDictParamsRec { 



CosObj rootObj; 


ASAtom transformMethod; 

CosObj transformParams; 

ASBool bIndirect; 

} DSSigRefDictParamsRec, *DSSigRefDictParams; 

Description 

Parameters used by methods that create a signature reference dictionary. See Section 8.7, 

"Digital Signatures," in the PDF Reference for more information on signature reference 

dictionaries. 

Members 

size 

cosDoc 

rootObj 

sigDict 


transformParams 

bIndirect 


sizeof(DSSigRefDictParamsRec). 

The document containing the object to be signed. 

The root object to be signed. 

The signature dictionary that this reference dictionary will be 

part of. 

The transform method name. Possible values are DocMDP, 

FieldMDP, UR and Identity. 

The transform parameters, which are specific to each transform 

method. 

true if the dictionary should be indirect, false if it should be 

direct. 

Header File 

DigSigHFT.h 




7 


DSSigRefErrCode 


kDSSigRefErrNone=0, 

kDSSigRefErrMissingPlugin, 

kDSSigRefErrNewVersion, 

kDSSigRefErrOldVersion, 

kDSSigRefErrEnumSize 

} DSSigRefErrCode; 

Description 

Error constants for signature reference dictionary procedures. 

Values 

kDSSigRefErrMissingPlugin 

kDSSigRefErrNewVersion 

kDSSigRefErrOldVersion 

Missing required plug-in or software module. 

Software module is named by errText in 

DSSigRefDictErrParams. 

New unsupported version of signature. 

Old unsupported version of signature. 

Header File 


DigSigHFT.h 






7 

DSValidState 


DSSigBlank=0, 

DSSigUnknown, 

DSSigInvalid, 

DSSigValid, 

DSSigDoubleChecked, 

DSSigValidStateEnumSize 

} DSValidState; 

Description 

A validity state constant for a signature field, resulting from verification. 

Values 

DSSigBlank 

DSSigUnknown 

DSSigInvalid 

DSSigValid 

DSSigDoubleChecked 

Signature field is unsigned. 

Signature field is signed, but not validated. 

Signature field is signed, but validation failed. 

Signature field is signed and valid. 

Signature field is signed and double-checked valid. 

Header File 


DigSigHFT.h 



DSGetValidStateProc 



7 


DSXObjType 


DSBlankXObj, 

DSUnknownXObj, 

DSInvalidXObj, 

DSValidXObj, 

DSDoubleCheckedXObj 

} DSXObjType; 

Description 

Structure describing the appearance of a digital signature. 

Members 

DSBlankXObj 

DSUnknownXObj 

DSInvalidXObj 

DSValidXObj 

DSDoubleCheckedXObj 

Blank appearance 

Signed but not validated appearance. 

Signed and failed validate appearance. 

Signed and valid, but identity not verified. 

Signed and valid and identity verified. 

Header File 

DigSigHFT.h 






8 

Digital Signature’s Use of Core API 

Objects 

The Digital Signatures Plug-in makes extensive use of the Acrobat Core API objects listed in 

this chapter. For information ,see Technical Note #5191, Acrobat Core API Reference. 

ASAtom 

A hashed token used in place of strings to optimize performance (it is much faster to 

compare ASAtoms than strings). 

ASCab 

A container object. 

ASFile 

An opaque representation of an open file. 

ASText 

A text object. 

AVPageView 

The area of the Acrobat viewer’s window that displays the contents of a document page. 

Every AVDoc has an AVPageView and vice versa. It contains references to the PDDoc and 

PDPage objects for the document being displayed. 

CosDoc 

A Cos level representation of an entire PDF file. 

CosObj 

A general object in a PDF file, which may be of any Cos object type. 


8 

Digital Signature’s Use of Core API Objects 

PDAnnot 

An annotation on a page in a PDF file. Acrobat viewers have two built-in annotation types: 

PDTextAnnot and PDLinkAnnot. Physical attributes of the annotation can be set and 

queried. Plug-ins add movie and Widget (form field) annotations. Developers can define 

new annotation subtypes by creating new annotation handlers. 

PDDoc 

The underlying PDF representation of a document. There is a correspondence between a 

PDDoc and an ASFile; the PDDoc object is the hidden object behind every AVDoc. An 

ASFile may have zero or more underlying files, so a PDF file does not always correspond 

to a single disk file. For example, an ASFile may provide access to PDF data in a database. 

Through PDDocs, your application can perform most of the Edit -> Pages menu items from 

Acrobat (delete, replace, and so on). Thumbnails can be created and deleted through this 

object. You can set and retrieve document information fields through this object as well. 

The first page in a PDDoc is page 0.

Acrobat Digital Signature API Reference - Adobe Partners

Create successful ePaper yourself

Delete template?

Save as template?