acrobat digital signature api reference - adobe · (408) 536-6000 bbc may, 2003 technical note...

ADOBE SYSTEMS INCORPORATED

Corporate Headquarters345 Park Avenue

San Jose, CA 95110-2704(408) 536-6000

http://partners.adobe.com

b bc

May, 2003

Technical Note #5192

Version: Acrobat 6.0

Acrobat Digital Signature API Reference

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 Developer FAQ

PDF Creation APIs and Specifications

Acrobat InterapplicationCommunication (IAC)

Acrobat Core API Extended API for Plug-in

Acrobat Core API Reference

Acrobat Distiller Parameters

Acrobat Distiller API Reference

pdfmark Reference

Digital Signature API Reference

Forms API Reference

Search API Reference

Weblink API Reference

Acrobat SDK Release Notes

Catalog API Reference

Acrobat SDK Samples Guide

Acrobat Core API Overview

Acrobat Plug-in Tutorial

Acrobat IAC Overview

Acrobat IAC ReferenceADM Programmer’s Guide and Reference

Getting Started Using the Acrobat Software Development Kit

Using the Save as XML Plug-in

Spelling API Reference

Acrobat SDK Documentation Roadmap

AcroColor API Reference

Acrobat Development Overview

PDF Consultant Accessibility Checker

PDF Reference Manual

JavaScript

Acrobat JavaScript Scripting Reference

Acrobat JavaScript Scripting Guide

Programming Acrobat JavaScript Using Visual Basic

Upgrading Plug-ins from Acrobat 5.0 to Acrobat 6.0

Reader EnablingPDF Specification

Getting Started

Acrobat Digital Signature API Reference 5

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23PSCloseEncryptedDocs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24PSCountEncryptedDocs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25PSDataBufferDigest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26PSDataBufferEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27PSExportDataExchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28PSImportDataExchange. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29PSRegisterHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30PSSigValidatePDDocSigField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Contents

6 Acrobat Digital Signature API Reference

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

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

AABFindCertsByName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33AABGetCertChain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34AABGetCertTrust . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35AABGetTrustedCerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36AABIsCertPresent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

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

DSAPFileAcquire . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38DSAPFileCanDeleteNthEntry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39DSAPFileCopyNthEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40DSAPFileEditNthEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41DSAPFileGetCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42DSAPFileGetNewNthName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43DSAPFileRelease . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44DSAPFileRemoveNthEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45DSAPFileSave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

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

PSDestroyEngineProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49PSExportDataProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50PSGetAtomPropertyProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51PSGetBoolPropertyProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52PSGetDirHandlerInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53PSGetDirInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54PSGetDirList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55PSGetImplicitRecipientsProc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56PSGetInt32PropertyProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57PSGetLogoProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58PSGetTextPropertyProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59PSImportDataProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60PSNewEngineProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61PSOpenCMSEnvelopeProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62PSOpenConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63PSPerformOperationProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64PSSessionAcquireProc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65PSSessionReadyProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66PSSessionReleaseProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67PSSetDirInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68PSSigAuthenticateProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69PSSigCreateAPNXObjProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70PSSigGetSigPropertiesProc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71PSSigGetSigValueProc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72PSSigPropDialogProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73PSSigValGetAPLabelProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74


Contents

PSSigValGetTextProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75PSSigValidateDialogProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76PSSigValidateProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77PSSigValidateSupportedProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

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

APPreview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79DirAuthenticationContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81DirConnection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82DirectoryInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83DirectoryList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85DirectoryInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86DirHandlerInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87DSAPFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88DSDigestMethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89DSPropertyType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90DSRetCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91DSSaveType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92DSSigValText. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93PSAPSigType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95PSDataBuffer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96PSExportDataExchangeParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97PSExportDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100PSExportDestType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101PSImportDataExchangeParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102PSImportDataParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103PSImportDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104PSOpenCMSEnvelopeParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105PSPerformOpType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106PSSessionOpType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107PSSigCosDocParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109PSSigDataBufferParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110PSSigDocType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111PSSigDialogStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112PSSigFileType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113PSSigMethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114PSSigPDDocParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115PSSigGetSigValueParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116PSSigSigPropParams. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118PSSigTrust . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120PSSigValidateParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121PSSigValidateDialogParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123PSSigValidateSupportParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125PSSigValSupport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126PubSecEngine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127PubSecHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128

Contents


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

DigSigAddedSig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133DigSigAddedSigEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134DSAPCreateCompositeTextXObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135DigSigAPCreateLayeredStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136DigSigAPCreateLayeredStreamEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138DigSigAPXObjectFromLogo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139DigSigAPXObjectFromXObjList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140DigSigByteToHex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141DigSigClearSig. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142DigSigClearSigRefDict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143DigSigClick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144DigSigCommitSigRefDict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145DigSigComparePages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146DigSigComparePagesEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147DigSigCompareWords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148DigSigCompareWordsAndFontsRecent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149DigSigCompareWordsEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150DigSigCompareWordsRecent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151DigSigCosObjOverwrite. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152DigSigCreateStdXObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154DigSigDeletedSig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155DigSigDeletedSigEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156DigSigDocModifiedAfterSig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157DigSigDoProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158DigSigDraw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159DigSigEnumSignatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160DigSigFileGetEOF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161DigSigFileRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162DigSigFileSetPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163DigSigFinishSigRefDict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164DigSigGetDocAuthorSignature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165DigSigGetDocMDPSetting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166DigSigGetStdXObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167DigSigGetUbiquitySignature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168DigSigGetUniqueTitle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169DigSigHexToByte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170DigSigIsDocSigned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171DigSigIsSigSigned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172DigSigKeyDown. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173DigSigMD5ByteRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .174DigSigNewSigRefDict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175DigSigOverwriteBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176DigSigOverwriteHexstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177DigSigOverwriteIntArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178DigSigRegisterFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179


Contents

DigSigRegisterObserver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .180DigSigRightClick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181DigSigRollbackToSig. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182DigSigSignDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183DigSigUnregisterFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184DigSigUnregisterObserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185DigSigUpdatePanel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186DigSigVerifySig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187DigSigVerifySigRefDict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188

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

DigSigEnumProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189DSCanValidateProc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190DSClearSigProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191DSCommitSignProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .192DSDefaultValueProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193DSDocCloseProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194DSDocOpenProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195DSFinishSignProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196DSFreeSigDataProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197DSGetBoolPropertyProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .198DSGetSigPropProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199DSGetStatusTextProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200DSGetValidStateProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201DSNewSigDataProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .202DSNewSigDataWithParamsProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .203DSNotificationProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204DSNotificationFailureProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205DSPropertiesProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206DSPropertiesExProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207DSReValidateSigProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .208DSSigDataGetErrorTextProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209DSUnValidateSigProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .210DSValidateSigProc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211

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

DigSigBBox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215DigSigHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .216DigSigNewSigDataParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219DigSigOffset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221DigSigOffsetRec. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221DSAPCreateLayeredStreamExParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222DSAPTextEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224DSAPXObjEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225

Contents


DSAPXObjEntryRec. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225DSComparePagesParams. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227DSCompareWordsParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228DSHandlerProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229DSMDPType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230DSNotificationType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231DSNotifyParams. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233DSOverwriteType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234DSQuadding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .235DSSigRefDictErrParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236DSSigRefDictParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237DSSigRefErrCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .238DSValidState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239DSXObjType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .240

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

ASAtom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241ASCab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241ASFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241ASText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241AVPageView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241CosDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241CosObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241PDAnnot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242PDDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .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.

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

PrefaceAudience


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

http://partners.adobe.com/asn


PrefaceConventions Used in This Book

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

Code examples set off from plain text

These are variable declarations:AVMenu commandMenu,helpMenu;

monospaced bold Code items within plain text

The GetExtensionID method ...

Parameter names and literal values in reference documents

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/

Live links to sections within this document

See Using the SDK.

Live links to other Acrobat SDK documents

See the Acrobat Core API Overview.

Live links to code items within this document

Test whether an ASAtom exists.

bold PostScript language and PDF operators, keywords, dictionary key names

The setpagedevice operator

User interface names The File menu

italic Document titles that are not live links

Acrobat Core API Overview

New terms User space specifies coordinates for...

PostScript variables filename deletefile

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

PrefaceConventions Used in This Book



1 Digital Signature Overview

Plug-in Relationships

The following figure illustrates the security plug-in relationships.

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.

Adobe Acrobat

Acrobat API PDCrypt

LegalPDFScrubber Agent(plug-in)

DigSig (plug-in)

DigSigHFT

PubSec PubSecHFT

Self-Sign(PPKLite Handler)

MSCAPI and ADSIinterface

(PPKMS Handler)

Acrobat Address Book(AAB Handler)

3rd partyPubSechandlers

Microsoft OS

CSP CSP CSP ...PKCS#12

File

User

FileContact

Digital Signature OverviewDigital Signature Components

1


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 plug-in does that transparently.


Digital Signature OverviewDigital 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.

Digital Signature OverviewUnderstanding the Process

1


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.

Understanding the Process

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

Return Value

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

Header File

PubSecHFT.h

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.

PubSec MethodsGeneral PubSec Methods

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

Return Value

true if successful, false otherwise.

Header File

PubSecHFT.h

Related Methods

PSCountEncryptedDocs

engine The engine for which the encrypted docs are closed.



2

PSCountEncryptedDocs

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

Return Value

None

Header File

PubSecHFT.h

Related Methods

PSCloseEncryptedDocs

engine The engine for which the encrypted docs are counted.

outNeedSave (Filled by the method) A pointer to the number of encrypted documents associated with the engine that need to be saved.

outCanClose (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.


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

Return Value


Header File

PubSecHFT.h

Related Methods

PSDataBufferEnum

dataBuffer The buffer containing the data.

digestValue (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.

digestMethod The method to use to compute the digest.



2

PSDataBufferEnum

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

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

Related Methods

PSDataBufferDigest

dataBuffer The buffer containing the data.

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

pReturnBuffer (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.

pReturnSize (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.


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

Return Value


Header File

PubSecHFT.h

Related Methods

PSImportDataExchange

params A structure containing the export parameters.



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

Return Value


Header File

PubSecHFT.h

Related Methods


params A structure containing the import parameters.


2


PSRegisterHandler

ASBool PSRegisterHandler (ExtensionID owner, PubSecHandler psHandler);

Description

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

Parameters

Return Value


Header File

PubSecHFT.h

Related Methods

PSUnregisterHandler

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

psHandler The handler structure containing the handler methods to register.



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 O T E : This method cannot validate a signature whose cache has not been updated or is NULL. In this case, use the method DigSigVerifySig.

Parameters

Return Value

true if the validation was successfully performed, false otherwise.

Header File

PubSecHFT.h

docParams The validation parameters.


2


PSUnregisterHandler

ASBool PSUnegisterHandler (PubSecHandler psHandler);

Description

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

Parameters

Return Value


Header File

PubSecHFT.h

Related Methods

PSRegisterHandler

psHandler The handler to unregister.


PubSec MethodsPubSec Acrobat Address Book Methods

2

Pu b S e c Acro b a t Ad d re s s B o o k M e t h o d s

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

Return Value


Header File

PubSecHFT.h

Related Methods

AABGetCertTrustAABGetTrustedCerts

inCertNameData The subject name of the certificates to find. Specify a BER-encoded value of ASN.1 type Name defined in X.509 (RFC 3280).

inCertNameSize The size of the certificate subject name data.

outResults (Filled by the method) An ASCab containing any certificates found by the lookup and their trust information.


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:

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

Parameters

Return Value


Header File

PubSecHFT.h

Related Methods

AABGetTrustedCerts

inX509Cert The certificate identifier, as defined in X.509 (RFC 3280). This is a generic 8-bit pointer to the certificate data.

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

inTrustedCerts An ASCab containing the user’s trusted certificates.

inUntrustedCerts An ASCab containing additional certificates needed to build the certificate chain.

outChain (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.



2

AABGetCertTrust

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

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

Related Methods

AABGetTrustedCertsAABIsCertPresent

inX509Cert The certificate identifier, as defined in X.509 (RFC 3280). This is a generic 8-bit pointer to the certificate data.

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

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

inHelperCerts 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), ... }


2


AABGetTrustedCerts

void AABGetTrustedCerts (PSSigTrust inTrust, ASCab outResults);

Description

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

Parameters

Return Value


Header File

PubSecHFT.h

Related Methods

AABGetCertTrust

inTrust The level of trust for which to find certificates. A logical OR of PSSigTrust bit flags.

outResults (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), ... }



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

Return Value

true if the certificate is found, false otherwise.

Header File

PubSecHFT.h

Related Methods

AABGetCertTrust

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

size The size of the certificate pointed to by x509.

PubSec MethodsDigital Signature Appearance File Methods

2


D i g i t a l S i g n at u re Ap p e a ra n ce Fi l e M e t h o d s

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

Return Value

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

Header File

PubSecHFT.h

Related Methods

DSAPFileRelease

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

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



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

Return Value

true if the entry is editable, false otherwise.

Header File

PubSecHFT.h

Related Methods

DSAPFileGetCountDSAPFileRemoveNthEntry

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


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

Return Value

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

Header File

PubSecHFT.h

Related Methods

DSAPFileCanDeleteNthEntryDSAPFileEditNthEntry

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



2

DSAPFileEditNthEntry

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

Return Value

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

Header File

PubSecHFT.h

Related Methods

DSAPFileCanDeleteNthEntryDSAPFileCopyNthEntry

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

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


2


DSAPFileGetCount

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

Related Methods

DSAPFileCanDeleteNthEntry



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

Return Value

A copy of the name as an ASText object.

Header File

PubSecHFT.h

Related Methods

DSAPFileGetCount

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


2


DSAPFileRelease

void DSAPFileRelease (void);

Description

Closes the digital signature appearance (DSAP) file.

Parameters

None

Return Value

None

Header File

PubSecHFT.h

Related Methods

DSAPFileAcquireDSAPFileSave



2

DSAPFileRemoveNthEntry

ASBool DSAPFileRemoveNthEntry (const ASInt32 index);

Description

Deletes the specified signature appearance entry from the DSAP file.

Parameters

Return Value


Header File

PubSecHFT.h

Related Methods

DSAPFileCanDeleteNthEntryDSAPFileGetCount

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


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

Related Methods

DSAPFileRelease



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

Return Value

None

Header File

PubSecHFT.h

Related Methods

PSNewEngineProc

engine The engine to be destroyed.

PubSec Callbacks3


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

Return Value

Positive on success.

Header File

PubSecHFT.h

Related Methods

PSImportDataProc

engine The engine for which the data is exported.

dataType The type of data to be exported.

outCab The ASCab containing the data to be exported.

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


PubSec Callbacks 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

Return Value

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

Header File

PubSecHFT.h

Related Methods

PSGetBoolPropertyProcPSGetInt32PropertyProcPSGetTextPropertyProc

engine The engine for which the property value is obtained.

szPropertyName The name of the ASAtom property whose value is obtained.

PubSec Callbacks3


PSGetBoolPropertyProc

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 PubSecEngine, see PubSecHFT.h.)

Parameters

Return Value

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

Header File

PubSecHFT.h

Related Methods

PSGetAtomPropertyProcPSGetInt32PropertyProcPSGetTextPropertyProc


szPropertyName The name of the ASBool property whose value is obtained.

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


PubSec Callbacks 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

Return Value


Header File

PubSecHFT.h

Related Methods

PSGetDirInfoPSGetDirListPSOpenConnectionPSSetDirInfo

engine The engine for which the information is obtained.

outDirHandlerInfo (Filled by the method) A structure containing an array of ASCab directory handlers.

PubSec Callbacks3


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

Return Value


Header File

PubSecHFT.h

Related Methods

PSGetDirHandlerInfoPSGetDirListPSOpenConnectionPSSetDirInfo


inDirID The unique identifier associated with the directory. See DirHandlerInfo.

outDirInfo (Filled by the method) An ASCab containing information about the directory.


PubSec Callbacks 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

Return Value


Header File

PubSecHFT.h

Related Methods

PSGetDirHandlerInfoPSGetDirInfoPSOpenConnectionPSSetDirInfo


outDirList (Filled by the method) An ASCab containing an array of DirectoryInfo ASCab objects.

PubSec Callbacks3


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

Return Value


Header File

PubSecHFT.h

Related Methods

PSGetDirInfoPSGetDirListPSSetDirInfo


outDirHandlerInfo (Filled by the method) An ASCab containing an array of ASCab directory handlers.


PubSec Callbacks 3

PSGetInt32PropertyProc

ACCB1 ASInt32 (ACCB2 *PSGetInt32PropertyProc)(PubSecEngine engine, const char* szPropertyName, const ASInt32 defaultValue);

Description

Gets an ASInt32 property of an engine. (For a list of public properties of a PubSecEngine, see PubSecHFT.h.)

Parameters

Return Value

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

Header File

PubSecHFT.h

Related Methods

PSGetAtomPropertyProcPSGetBoolPropertyProcPSGetTextPropertyProc


szPropertyName The name of the ASInt32 property whose value is obtained.

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

PubSec Callbacks3


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

Return Value

None

Header File

PubSecHFT.h

Related Methods

PSSigCreateAPNXObjProcPSSigValGetAPLabelProc

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

pcLogo (Filled by the method) A string of the uncompressed graphics stream for the logo artwork.

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


PubSec Callbacks 3

PSGetTextPropertyProc

ACCB1 ASText (ACCB2 *PSGetTextPropertyProc)(PubSecEngine engine, const char* szPropertyName, const ASInt32 index);

Description

Gets an ASText property of an engine. (For a list of public properties of a PubSecEngine, see PubSecHFT.h.)

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

Return Value

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

Header File

PubSecHFT.h

Related Methods

PSGetAtomPropertyProcPSGetBoolPropertyProcPSGetInt32PropertyProc


szPropertyName The name of the ASText property whose value is obtained.

index The index of the string to obtain if the property contains a list of values. If it does not, index is ignored.

PubSec Callbacks3


PSImportDataProc

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

Return Value


Header File

PubSecHFT.h

Related Methods

PSExportDataProc


params A structure that contains the data to be imported.

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


PubSec Callbacks 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

Related Methods

PSDestroyEngineProc

PubSec Callbacks3


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

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


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

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


PubSec Callbacks 3

PSOpenConnection

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

Return Value

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

Header File

PubSecHFT.h

Related Callbacks

PSGetDirHandlerInfoPSGetDirInfoPSGetDirListPSSetDirInfo

engine The engine for which the connection is opened.

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

inAuthCtx Not currently supported. Pass as NULL.

inUI Whether the authentication UI should be shown.

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

PubSec Callbacks3


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

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

engine The engine for which the operation is performed.

type The type of operation to perform.

cab An ASCab containing parameters for the requested operation, or NULL to test whether the operation is supported.

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


PubSec Callbacks 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

Return Value


Header File

PubSecHFT.h

Related Methods

PSSessionReadyProcPSSessionReleaseProc


pdDoc The PDF document for which the session is acquired.

opType The operation that is the reason for acquiring the session.

opText A human-readable version of the reason for acquiring the session. If not supplied, opType is used to build text.

cabParams An ASCab object containing information about the acquisition, owned by PubSec. Currently not used, passed as NULL.

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

PubSec Callbacks3


PSSessionReadyProc

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

Return Value

kDSTrue if the session is ready, otherwise kDSFalse.

Header File

PubSecHFT.h

Related Methods

PSSessionAcquireProcPSSessionReleaseProc


opType The operation for which the session is needed.


PubSec Callbacks 3

PSSessionReleaseProc

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

Return Value

kDSTrue if the session is successfully released, otherwise kDSFalse.

Header File

PubSecHFT.h

Related Methods

PSSessionAcquireProcPSSessionReadyProc

engine The engine for which the session was acquired.

opType The operation for which the session was needed.

PubSec Callbacks3


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

Return Value

kDSOk if successful, otherwise an exception code.

Header File

PubSecHFT.h

Related Methods

PSGetDirHandlerInfoPSGetDirInfoPSGetDirListPSOpenConnection


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.


PubSec Callbacks 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

Return Value

kDSTrue if authentication succeeds, kDSFalse if authentication fails.

Header File

PubSecHFT.h

Related Methods

PSGetBoolPropertyProcPSSigGetSigValueProcPSSigValidateProc

engine The engine for which signature authentication is performed.

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

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

bInUIAllowed When true, the call can invoke the authentication UI.

PubSec Callbacks3


PSSigCreateAPNXObjProc

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

Return Value


Header File

PubSecHFT.h

Related Methods

PSGetLogoProcPSSigValGetAPLabelProc

engine The engine for which an appearance is created.

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

docParams A validation parameters structure containing information that is needed to create the signature appearance, such as the PDDoc and annotation.

sigType The signature type.


PubSec Callbacks 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

Return Value


Header File

PubSecHFT.h

Related Methods

PSGetLogoProcPSSessionAcquireProcPSSigValGetAPLabelProcPSSigGetSigValueProc

engine The engine for which signature properties are retrieved.

params A signature properties parameters structure.

PubSec Callbacks3


PSSigGetSigValueProc

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

Return Value


Header File

PubSecHFT.h

Related Methods

PSSigAuthenticateProcPSSigGetSigPropertiesProcPSSigValidateProc

engine The engine for which a signature value is created.

params (Modified by the method) A structure containing signature-value parameters and return values.


PubSec Callbacks 3

PSSigPropDialogProc

ACCB1 DSRetCode (ACCB2 *PSSigPropDialogProc)(PubSecEngine engine, 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 handler-provided display dialog. Otherwise, the button opens the default certificate-display dialog.

Parameters

Return Value


Header File

PubSecHFT.h

Related Methods

PSSigValidateDialogProc

engine The engine for which the validation status is shown.

valParams (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.

PubSec Callbacks3


PSSigValGetAPLabelProc

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

Return Value

The label of a signature appearance layer as an ASAtom.

Header File

PubSecHFT.h

Related Methods

PSGetLogoProcPSSigCreateAPNXObjProc

valCab An ASCab containing the signature validation result for which the label is obtained.

layerNum The layer for which a label is obtained.


PubSec Callbacks 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

Return Value

The text result of validation as a new ASText object.

Header File

PubSecHFT.h

Related Methods

PSSigValidateProcPSSigValidateDialogProc

valCab The ASCab containing the validation result. (See PSSigValidateParams.)

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

index If the type is kDSSigValTextAP, the corresponding index value. Otherwise ignored.

PubSec Callbacks3



ACCB1 DSRetCode (ACCB2 *PSSigValidateDialogProc)(PubSecEngine engine, 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

Return Value


Header File

PubSecHFT.h

Related Methods

PSSigAuthenticateProcPSSigGetSigValueProcPSSigPropDialogProcPSSigValidateProcPSSigValidateSupportedProc

engine The engine for which the validation status is shown.

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


PubSec Callbacks 3

PSSigValidateProc

ACCB1 DSRetCode (ACCB2 *PSSigValidateProc)(PubSecEngine engine, PSSigValidateParams params )

Description

Called to validate a signature.

Parameters

Return Value


Header File

PubSecHFT.h

Related Methods

PSSigAuthenticateProcPSSigGetSigValueProcPSSigValidateDialogProcPSSigValidateSupportedProc

engine The engine for which the signature is validated.

params (Modified by the method) A signature validation parameters and return values structure. The result of validation is stored in the sigValCab field.

PubSec Callbacks3


PSSigValidateSupportedProc

ACCB1 PSSigValSupport (ACCB2 *PSSigValidateSupportedProc)(PubSecEngine engine, PSSigValidateSupportParams params )

Description

Called to determine whether the handler can validate a signature.

Parameters

Return Value

A signature-validation support value.

Header File

PubSecHFT.h

Related Methods

PSSigAuthenticateProcPSSigGetSigValueProcPSSigValidateDialogProcPSSigValidateProc

engine The engine for which the signature is validated.

params A parameters structure containing information about the signature to be validated.


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 The logo string.

logoBBox The bounding box for the logo string.

fName The entry name.

fDN The distinguished name.

fReason The reason for signing.

fLocation The location of signing.

fWidthfHeight

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

fbAuthSig true if this is an author signature, false otherwise.

PubSec Declarations4


Header File

PubSecHFT.h

Related Methods

DSAPFileEditNthEntry


PubSec Declarations 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

Related Callbacks

PSOpenConnection



DirConnection

typedef struct _t_DirConnection* DirConnection;

Description

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

Header File

DirectoryHFT.h

Related Callbacks

PSOpenConnection



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) Language-independent 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) Language-independent name for the type of the directory; for example, LDAP. Required when entries are to be imported or exported.



Header File

DirectoryHFT.h

Related Callbacks

PSGetDirInfo PSGetDirHandlerInfo

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.

Property Type Description



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

Related Callbacks

PSGetDirList



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:

Header File

PubSecHFT.h

Related Callbacks

PSGetDirHandlerInfo

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.



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:

Header File

PubSecHFT.h

Related Callbacks

PSGetDirHandlerInfo

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.



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

Related Methods

DSAPFileAcquire



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

Related Methods

PSDataBufferDigest



DSPropertyType

typedef enum {kDSPropNone=0,kDSPropSignature,kDSPropLegal,kDSPropViewVersion,kDSPropTypeEnumSize

} DSPropertyType;

Description

Constants that specify what dialog to show.

Values

Header File

DigSigHFT.h

Related Structures

PSSigValidateDialogParams

Related Callbacks


kDSPropNone Do not show signature properties dialog.

kDSPropSignature Show general signature properties dialog.

kDSPropLegal Show legal notice dialog.

kDSPropViewVersion Show signature rollback (will actually rollback to this signature).



DSRetCode

typedef ASInt32 DSRetCode;

Description

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

Values

Header File

DigSigHFT.h

Related Methods

numerous

kDSException (-2) 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.

kDSParameterError (-1) Error in a parameter to the function call. No exception string.

kDSFalse (0)kDSTrue (1)

A boolean return value.

kDSOk (1) Success.



DSSaveType

typedef enum { DSSignCancel=0,DSSignSave,DSSignSaveAs,DSSaveTypeEnumSize

} DSSaveType;

Description

A return type for DigSig and PubSec callback.

Values

Header File

DigSigHFT.h

Related Callbacks

PSSigGetSigPropertiesProcDSNewSigDataWithParamsProc

DSSignCancel Do not proceed with signing.

DSSignSave Save over old file.

DSSignSaveAs Save to new file.



DSSigValText

typedef enum {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 Never called, should return NULL.

kDSSigValTextDSTop Optional. Get text to show in AVPanel, added to end of signature summary line.

kDSSigValTextDSDetail Optional. Get text to show in AVPanel, shown in signature detail title line.

kDSSigValTextDSTooltip Optional. Get text to show in tooltip when mouse is over signature annotation.

kDSSigValTextSigInfo Optional. Get text to show in EScript SignatureInfo object.

kDSSigValTextVal Optional. Get text to show in validate alert dialog.



Header File

PubSecHFT.h

Related Callbacks

PSSigValGetTextProc

kDSSigValTextProp Optional. Get text to show in signature properties dialog.

kDSSigValTextAP Optional. Get text to show in appearance, if signature appearance uses layer n4 (not recommended). In this case, you must also pass an index.

kDSSigValTextPropIdValidity Get text to describe validity of the signer certificate (used in properties and validity dialogs).

kDSSigValTextDSAVIdValidity Get text to describe validity of the signer certificate (used in AVPanel).

kDSSigValTextDSTTIdValidity Get text to describe validity of the signer certificate (appended to tooltip, called only when describing why certificate is invalid).



PSAPSigType

typedef enum { kPSAPSigPreExists=0, kPSAPSigTentative,kPSAPSigPreview

} PSAPSigType;

Description

A signature type to use for generating a signature appearance.

Values

Header File

PubSecHFT.h

Related Callbacks

PSSigCreateAPNXObjProc

kPSAPSigPreExists Signing a pre-existing signature field.

kPSAPSigTentative Creating a signature on the fly on a page.

kPSAPSigPreview Creating a preview of a signature.



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

Related Methods

PSDataBufferDigestPSDataBufferEnum



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 The size of the structure.

psHandler If exporting FDF, the handler to use to sign the FDF. If not supplied, the user is prompted for a handler

psEngine If exporting FDF, the engine to use to sign the FDF. If not supplied, the method uses the default (UI) engine.

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

dataCab Required. Data to export, or an empty ASCab if there is no data to export. Format defined below.

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



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" : "[email protected]""Certs" : Cab

"0" : binary end entity cert"cn" : "John Smith""EMail" : "[email protected]"

Example cab for exporting directory settings:

dataCab : Cab"DirSettings" : Cab

"0" : Cab"Port" : 369

Header File

PubSecHFT.h

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.



Related Methods




PSExportDataType

typedef enum { kPSExportDataNone=0,kPSExportDataMyContact,kPSExportDataContacts,kPSExportDataDirSettings,kPSExportDataEnumSize

} PSExportDataType;

Description

The format of data to be exported using PSExportDataProc or PSExportDataExchange.

Members

Header File

PubSecHFT.h

Related Callbacks

PSExportDataProc

Related Methods


kPSExportDataNone None. No export operation is performed.

kPSExportDataMyContact Export certificates for self.This operation is performed only if the PROP_PSENG_ExportContact property is set, indicating that the handler supports this format.

kPSExportDataContacts Export a list of entries from an address book.This operation is performed only if the PROP_PSENG_ExportContact property is set, indicating that the handler supports this format.

kPSExportDataDirSettings Export a list of directory settings. This operation is performed only if the PROP_PSENG_ExportDirSettings property is set, indicating that the handler supports this format.

kPSExportDataEnumSize The size of the enum



PSExportDestType

typedef enum { kPSExportDestNone=0,kPSExportDestFile,kPSExportDestCMSFile,kPSExportDestCertFile,kPSExportDestFDFFile,kPSExportDestEMailFDF,kPSExportDestCertURL,kPSExportDestEnumSize

} PSExportDestType;

Description

File output options for PSExportDataExchangeParams.

Members

Header File

PubSecHFT.h

Related Callbacks

PSExportDataProc

Related Methods


kPSExportDestNone None, prompt for output file type. Recommended.

kPSExportDestFile Save as unspecified file type, possibly prompting for the file type.

kPSExportDestCMSFile Save as CMS file (.p7c).

kPSExportDestCertFile Save as Certificate file (.cer).

kPSExportDestFDFFile Save as FDF file.

kPSExportDestEMailFile Email FDF file.

kPSExportDestCertURL Send single certificate to URL.



PSImportDataExchangeParams

typedef struct _t_PSImportDataExchangeParamsRec {ASSize_t size;PubSecHandler psHandler;PubSecEngine psEngine;PSExportDataType dataType; ASFileSys fileSys;ASPathName filePath;

} PSImportDataExchangeParamsRec, *PSImportDataExchangeParams;

Description

Parameters for importing data from a file into PubSec.

Members

Header File

PubSecHFT.h

Related Methods



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

psEngine The engine to use to accept the import data. If not supplied, the method uses the default (UI) engine.

dataType The type of data to be imported. If data of this type is not found in the FDF, the operation fails. .

fileSys The file system used for filePath.

filePath The path of the file to be opened for import.



PSImportDataParams

typedef struct _t_PSImportDataParamsRec {ASSize_t size;PSImportDataType dataType; ASCab dataCab; PSSigTrust sigTrust;

} PSImportDataParamsRec, *PSImportDataParams;

Description

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

Members

Header File

PubSecHFT.h

Related Callbacks

PSImportDataProc


dataType The format of the data to be imported.

dataCab ● If dataType is kPSImportDataSigDict, the signature dictionary.

● If dataType is kPSImportDataFDFImportArray, the import array.

● If dataType is kPSImportDataFDFDirArray, the directory settings array.

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



PSImportDataType

typedef enum {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

Header File

PubSecHFT.h

Related Callbacks

PSImportDataProc

kPSImportDataNone None. No import operation is performed.

kPSImportDataContactsCab An ASCab containing a list ("0", "1", ...) of contact cabs. Contact cabs have the entries PROP_ContactCab_*.

kPSImportDataContactsCabFromSig

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.

kPSImportDataDirsCab An ASCab containing a list ("0", "1", ...) of dir setting cabs. DirSetting cabs have the entries PROP_DirSettingCab_*..

kPSImportDataEnumSize The size of this enum



PSOpenCMSEnvelopeParams

typedef struct _t_PSOpenCMSEnvelopeParamsRec {ASSize_t size;const ASUns8* cmsEnvelopeData;ASUns32 cmsEnvelopeSize;ASUns8* outEnvelopeContentsData;ASUns32 outEnvelopeContentsSize;ASUns8* outSessionKeyData;ASUns32 outSessionKeySize;ASUns8* outOpeningCertData;ASUns32 outOpeningCertSize;

} PSOpenCMSEnvelopeParamsRec, *PSOpenCMSEnvelopeParams;

Members

size The size of this structure.

cmsEnvelopeData Constant. The ASN1 encoded PKCS#7 Enveloped Data to open.

cmsEnvelopeSize Size in bytes of the data pointed to by cmsEnvelopeData.

outEnvelopeContentsData Returns the envelope contents data. PubSec owns, allocates and frees the memory.

outEnvelopeContentsSize Size in bytes of the data pointed to by cmsEnvelopeContentsData.

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

outSessionKeySize Size in bytes of the data pointed to by outSessionKeyData.

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

outOpeningCertSize Size in bytes of the data pointed to by outOpeningCertData.



PSPerformOpType

typedef enum {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

Header File

PubSecHFT.h

Related Callbacks

PSPerformOperationProc

kPSOpPerformNone None

kPSOpPerformESLoginkPSOpPerformESLogoutkPSOpPerformESNewUserkPSOpPerformESSetValidateMethodkPSOpPerformESPasswordTimeout

Silent, scripted operations

kPSOpPerformDisplayCertList Brings up a UI to display a list of certificates contained in an ASCab. Returns true if implemented by the handler

kPSOpPerformGetCerts Returns a list of certificates in an ASCab.



PSSessionOpType

typedef enum { 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 None

kPSOpTypePDDocSign Sign a PDDoc to create a PDDoc signature.

kPSOpTypePDDocSigValidate Validate a PDDoc signature.

kPSOpTypeCosDocSign Sign a cosDoc.

kPSOpTypeCosDocSigValidate Validate a cosDoc signature.

kPSOpTypeDataSign Sign bytes.

kPSOpTypeDataSigValidate Validate bytes.

kPSOpTypeMyContactExport Read and export My Contact information.

kPSOpTypeContactImport Import contacts into address book.



Header File

PubSecHFT.h

Related Callbacks

PSSessionAcquireProcPSSessionReadyProcPSSessionReleaseProc

kPSOpTypePolicyModify Modify credential access policy (used by EScript).

kPSOpTypeAPRead Read an appearance file (used by EScript).

kPSOpTypePDCryptDocCreate Prepare to encrypt docsuments.

kPSOpTypePDCryptDocOpen Prepare to open encrypted documents.

kPSOpTypeLogin Authenticate or login user (used by EScript).

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

kPSOpTypeCertEnum Enumerate certificates available for signing and encryption.

kPSOpTypeDirEnum Enumerate directories and get directory information.

kPSOpTypeDirGet Connect to and use directory.



PSSigCosDocParams

typedef struct _t_PSSigCosDocParamsRec {ASSize_t size;PSSigDocType sigType; PDDoc pdDoc;CosDoc cosDoc; CosObj sigDict;

} PSSigCosDocParamsRec, *PSSigCosDocParams;

Description

Signature parameters for a cosDoc. Used internally.

Members

Header File

PubSecHFT.h

Related Callbacks


Related Structures

PSSigSigPropParams


sigType Constant. Always kPSSigDocTypeCosDoc.

pdDoc Constant. Null if no parent.

cosDoc Constant. The document being signed.

sigDict Constant. The signature dictionary.



PSSigDataBufferParams

typedef struct _t_PSSigDataBufferParamsRec {ASSize_t size;PSSigDocType sigType; PDDoc pdDoc;CosDoc cosDoc;

} PSSigDataBufferParamsRec, *PSSigDataBufferParams;

Description

Signature parameters for signing transitional data, such as XFA.

Members

Header File

PubSecHFT.h

Related Callbacks


Related Structures

PSSigSigPropParams


sigType Constant. Always kPSSigDocTypeCosDoc.

pdDoc Constant. NULL if no parent.

cosDoc Constant. The document being signed.



PSSigDocType

typedef enum {kPSSigDocTypeNone=0,kPSSigDocTypePDDoc,kPSSigDocTypeCosDoc, kPSSigDocTypeTransData, kPSSigDocTypeEnumSize

} PSSigDocType;

Description

The type of document being signed.

Values

Header File

PubSecHFT.h

Related Structures

PSSigPDDocParamsPSSigSigPropParamsPSSigValidateDialogParams

kPSSigDocTypePDDoc A PDF document.

kPSSigDocTypeCosDoc An FDF file.

kPSSigDocTypeTransData Reserved for future use.



PSSigDialogStatus

typedef enum {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

Related Structures

PSSigSigPropParams

Related Callbacks


kPSSigDialogNone No further dialogs required.

kPSSigDialogSign PubSec's sign dialog should be executed

kPSSigDialogSignWithPassword PubSec's sign dialog should be executed, and ask for password.

kPSSigDialogSignThenAuthenticate PubSec's sign dialog should be executed, then SigAuthenticate should be called.



PSSigFileType

typedef enum {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

Header File

PubSecHFT.h

Related Structures

PSSigSigPropParams

kPSFileNone Uninitialized.

kPSFileAVDoc Normal PDDoc signing. Enable Save and SaveAs buttons

kPSFileBrowserDoc Signing a PDDoc in an external browser window. Enable Sign button.

kPSFileExternalDoc Signing a PDDoc in an external non-browser window. Enable Sign button.

kPSFileTempDoc Signing a temporary file. Enable SaveAs button

kPSFileFDFData Signing an FDF Data Exchange file. Enable Sign button.

kPSFileCosDoc Signing a cosDoc. Enable Sign button.

kPSFileTransData Signing transactional data.



PSSigMethod

typedef enum {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

Header File

PubSecHFT.h

Related Structures

PSSigGetSigValueParams

Related Callbacks


kPSSigMethodNone None

kPSSigMethodPKCS1 PKCS#1, adbe.x509.rsa.sha1

kPSSigMethodPKCS7Detached adbe.pkcs7.detached

kPSSigMethodPKCS7SHA1 adbe.pkcs7.sha1



PSSigPDDocParams

typedef struct _t_PSSigPDDocParamsRec {ASSize_t size;PSSigDocType sigType; 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

Header File

PubSecHFT.h

Related Methods

PSSigValidatePDDocSigField

Related Callbacks

PSSigGetSigPropertiesProcPSSigCreateAPNXObjProc

Related Structures

PSSigSigPropParams


sigType Constant. Always kPSSigDocTypePDDoc.

pdDoc Constant. The document being signed.

sigField Constant. The field being signed.

sigAnnot Constant. The annotation associated with this field.

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

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

sigAPCab Returns handler-specific appearance information for PSSigGetSigPropertiesProc.



PSSigGetSigValueParams

typedef struct _t_PSSigGetSigValueParamsRec {ASSize_t size;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

Header File

PubSecHFT.h


sigMethod Constant. The method used to create the signature value.

digestMethod Constant. The method used to create the digest.

digestValue Constant. A digest value to be signed or NULL.

dataBuffer The handle to use for fetching bytes to digest.

bGetSigValue Constant. If true, get a signature value, otherwise return the size of the signature value.

outSigValueData Return the signature value data. Caller will call ASfree to destroy the structure.

outSigValueSize Return size of the signature value.

outSigPropCab Return an ASCab containing signature properties that should be displayed instead of signature dictionary entries.



Related Callbacks




PSSigSigPropParams

typedef struct _t_PSSigSigPropParamsRec {ASSize_t size;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


pdDoc Constant. The pdDoc being signed. If not signing a pdDoc , this is only used for window parenting and can be NULL.

fileOptions Constant. The file type and signing environment, which the handler uses to put up appropriate save buttons.

bUI Constant. When true , the call is being made from the UI, when false it is being made from a script or batch file.

dialogTitle Title to use for the signing dialog, if bUI is true. Usually NULL, which allows the handler to use the default.

sigParamsCab Constant. Parameters passed in by EScript converted to an ASCab, or NULL if the call is not from EScript.

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



Header File

PubSecHFT.h

Related Callbacks


outDialogStatus Return status information that tells PubSec what dialogs to put up and how to authenticate the handler.

outCertListCab Required. Return an ASCab containing an ordered certificate chain, signing certificate first (at key 0).

outNewSigPropCab Required. Populate this existing ASCab with signature properties that will be written to the signature dictionary when the signature is committed.

outNewSigBuildCab Optional. Populate this existing ASCab with return build properties that will be written to the signature dictionary when the signature is committed.

docType Constant. The type of document being signed.

docParams A structure containing signature parameters appropriate to the type of document. Depending on sigType, a structure of type PSSigPDDocParams, PSSigCosDocParams, or PSSigDataBufferParams.



PSSigTrust

Description

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

Values

Header File

PubSecHFT.h

Related Methods

AABGetTrustedCerts

Related Structures

PSImportDataParams

kPSSigTrustUntrusted Certificate is untrusted.

kPSSigTrustSigning Trusted for signing (creating recipient signatures).

kPSSigTrustAuthenticDocuments Trusted for authoring documents (creating author signatures).

kPSSigTrustDynamicContent Trusted for authoring documents with dyamic (multimedia) content.

kPSSigTrustUbiquity Trusted for feature-enabling signatures (Adobe internal use only).

kPSSigTrustJavaScript Trusted for authoring documents with full-access JavaScript.

kPSSigTrustAll Trusted for everything.



PSSigValidateParams

typedef struct _t_PSSigValidateParamsRec {ASSize_t size;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


sigMethod Constant. The method used to create the signature value.

digestMethod Constant. The method used to create the digest.

digestValue Constant. A digest value to be signed or NULL.

sigValueData Constant. A signature value to be verified.

sigValueSize Constant. The size of the signature value.

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



Header File

PubSecHFT.h

Related Callbacks

PSSigValidateProc

reqRevokeChecks Informs the handler whether revocation checks are required. Handlers should always do revocation checks, but return failure only when this value is true.

maxRevokeInfoCacheLifetime 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).

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

outSigPropCab Returns signature properties to display instead of signature dictionary entries.

dataBuffer The handle to use for fetching bytes to digest.



PSSigValidateDialogParams

typedef struct _t_PSSigValidateDialogParamsRec {ASSize_t size;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


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

reqRevokeChecks Informs the handler whether revocation checks are required. Handlers should always do revocation checks, but return failure only when this value is true.

maxRevokeInfoCacheLifetime 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).

sigValCab An ASCab containing the validity of the signature. Never NULL. The handler can validate the signature and update this object if desired.



Header File

PubSecHFT.h

Related Callbacks


bModalParent Indicates whether being called when a modal parent dialog is open. If true, rollback and verify buttons should be disabled becausei) rollback is not possible while modal parent is open; (ii) verify status may not get propagated properly to various caching locations.

dsPropType Returns a value that tells PubSec whether to rollback the signature or show a properties dialog for the signature.

docType Constant. The type of document being signed.

docParams A structure containing signature parameters appropriate to the type of document. Depending on sigType, a structure of type PSSigPDDocParams or PSSigCosDocParams.



PSSigValidateSupportParams

typedef struct _t_PSSigValidateSupportParamsRec {ASSize_t size;ASAtom filter;ASAtom subFilter;ASInt32 version;ASInt32 revision;ASCab buildCab;

} PSSigValidateSupportParamsRec, *PSSigValidateSupportParams;

Description

A structure containing signature parameters for PSSigValidateSupportedProc.

Members

Header File

PubSecHFT.h

Related Callbacks



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

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

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

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

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



PSSigValSupport

typedef enum {kPSSigValSupportFalse,kPSSigValSupportTrue,kPSSigValSupportUpdate,kPSSigValSupportPreRelease,kPSSigValSupportEnumSize

} PSSigValSupport;

Description

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

Values

Header File

PubSecHFT.h

Related Callbacks


kPSSigValSupportFalse The handler does not support validationof this signature.

kPSSigValSupportTrue The handler supports validationof this signature.

kPSSigValSupportUpdate A handler software update is needed to support validation of this signature.

kPSSigValSupportPreRelease The signature was created with a pre-release or invalid release of the software. Warns user.



PubSecEngine

typedef void* PubSecEngine;

Description

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

Header File

PubSecHFT.h

Related Methods

PSCloseEncryptedDocsPSCountEncryptedDocs



PubSecHandler

typedef struct _t_PubSecHandlerRec {ASSize_t size;_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




nextdsHandlercryptHandler

Used internally.

engine Engine to use for UI-based execution.

newEnginedestroyEngine

Engine constructor and destructor.

getBoolPropertygetAtomPropertygetInt32PropertygetTextProperty

Property retrieval methods.

sessionAcquiresessionReleasesessionReadyperformOperation

Session operation methods.

sigGetSigPropertiessigAuthenticatesigGetSigValue

Signature methods.

sigValidatesigValidateDialogsigPropDialogsigValGetTextsigValGetText

Validation methods

getLogosigValGetAPLabelsigCreateAPNXObj

Signature appearance methods.

importDataexportData

Contact exchange methods.

cryptOpenCMSEnvelopecryptGetImplicitRecipients

Encryption methods.

dirGetDirHandlerInfodirGetDirListdirGetDirInfodirSetDirInfodirOpenConnection

Directory Service Provider methods.



Header File

PubSecHFT.h

Related Methods

PSRegisterHandlerPSUnregisterHandler


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

Return Value

None

Header File

DigSigHFT.h

Related Methods

DigSigAddedSigExDigSigDeletedSig

pdDoc The document that contains the signature field.

Digital Signature Methods5


DigSigAddedSigEx

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

Return Value

None

Header File

DigSigHFT.h

Related Methods

DigSigAddedSigDigSigDeletedSigEx


cosField The signature field that was added.


Digital Signature Methods 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

Return Value

The new XObject that contains the text.

Header File

DigSigHFT.h

Related Methods

DigSigAPXObjectFromLogoDigSigAPXObjectFromXObjList

cosDoc The document.

inText The text to include.

bbox The bounding box, which must already compensate for rotation and position within the annotation.

sigField The signature field object.

sigAnnot The signature annotation object.



DigSigAPCreateLayeredStream

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);

Description

N O T E : 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)

Parameters

cosDoc The document in which to include the standard XObject.

layer1XObject The middle layer.

layer1Matrix The position the first layer object.

layer2XObject The text and appearance layer.

layer2Matrix The position the second layer object.

layer3XObject The top layer.

layer3Matrix The position the third layer object.

layerNXObject An optional validity state layer.

layerNum The layer number for the optional validity state layer.

border The border from AFPDWidgetGetBorder.

cBorder The color of the border.



Return Values

A new CosStream composed of different layers.

Header File

DigSigHFT.h

Related Methods


cBackGnd color of the background.

width The width of the new stream object.

height The height of the new stream object.

pdr The rotational parameter from AFPDWidgerGetRotation.



DigSigAPCreateLayeredStreamEx

CosObj DigSigAPCreateLayeredStreamEx (const DSAPCreateLayeredStreamExParams params)

Description

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

N O T E : Supersedes DigSigAPCreateLayeredStream in Acrobat 6.0.

Parameters

Return Values

A new CosStream composed of different layers.

Header File

DigSigHFT.h

Related Methods


params The parameter structure containing the signature appearance layer information.



DigSigAPXObjectFromLogo

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

Return Value

A Cos object XObject that contains the logo.

Header File

DigSigHFT.h

Related Methods

DSAPCreateCompositeTextXObjDigSigAPCreateLayeredStreamDigSigAPXObjectFromXObjList

cosDoc The document.

logoStr The stream containing the text.

logoStrSize The length of the logo string, or 0 to calculate the length automatically.

logoBbox The bounding box for logoStr.

bbox The bounding rectangle of the result.



DigSigAPXObjectFromXObjList

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

Return Value

XObject composed from list.

Header File

DigSigHFT.h

Related Methods

DSAPCreateCompositeTextXObjDigSigAPCreateLayeredStreamDigSigAPXObjectFromLogo


bbox The bounding box for the signature.

objEntry A list of DSAPXObjEntry objects.

ta The text appearance. For an explanation of the TextAppearanceP type, see "AcroForm Declarations" in Acrobat Forms API Reference.

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

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



DigSigByteToHex

void DigSigByteToHex (unsigned char* byteP, unsigned char* hexP, ASInt32 length);

Description

Converts a byte string to a PDF hex string.

Parameters

Return Value

None

Header File

DigSigHFT.h

Related Methods

DigSigHexToByte

byteP A pointer to the byte string.

hexP (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 “<“ and ends with “>”, followed by a NULL character. For example, the two byte string “A/” is converted to “<412f>\0.”

length The length of the byte string, in bytes



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

Return Value

None

Header File

DigSigHFT.h

Related Methods

DigSigVerifySig

pdDoc The document.

sigField The signature field to clear.



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

Return Value


Header File

DigSigHFT.h

Related Methods

DigSigCommitSigRefDictDigSigFinishSigRefDictDigSigNewSigRefDictDigSigVerifySigRefDict

transformMethod The transform method. It should match the one contained in sigDict.

sigDict The signature dictionary containing the signature reference dictionary.

refDict The signature reference dictionary.



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

Return Value

None

Header File

DigSigHFT.h

Related Methods

DigSigDrawDigSigHexToByteDigSigRightClick

pdAnnot The annotation the user clicked on

avPV The page view that contains the annotation.

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

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

nFlags 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

nClicks The number of clicks.



DigSigCommitSigRefDict

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

Return Value

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

Header File

DigSigHFT.h

Related Methods

DigSigClearSigRefDictDigSigFinishSigRefDictDigSigNewSigRefDictDigSigVerifySigRefDict

transformMethod The transform method.

sigDict The signature dictionary that contains the signature reference dictionary.

refDict (Filled by the method) A pointer to the committed signature reference dictionary.



DigSigComparePages

ASBool DigSigComparePages (PDDoc docA, PDDoc docB, ASBool insertDiffs);

Description

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

N O T E : Superceded by DigSigComparePagesEx in Acrobat 6.0.

Parameters

Return Value

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

Header File

DigSigHFT.h

Related Methods

DigSigCompareWords

docA First document to compare.

docB Second document to compare.

insertDiffs Not used.



DigSigComparePagesEx

ASBool DigSigComparePagesEx (PDDoc docA, PDDoc docB, DSComparePagesParams params);

Description

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

Parameters

Return Value

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

Header File

DigSigHFT.h

Related Methods

DigSigComparePagesDigSigCompareWords

docA First document being compared.

docB Second document being compared.

params A structure containing the sensitivity level for the comparison.



DigSigCompareWords

ASBool DigSigCompareWords (PDDoc docA, PDDoc docB, ASBool iUseFonts);

Description

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

N O T E : Superceded by DigSigCompareWordsEx in Acrobat 6.0.

Parameters

Return Value

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

Header File

DigSigHFT.h

Related Methods

DigSigComparePagesDigSigCompareWordsAndFontsRecentDigSigCompareWordsExDigSigCompareWordsRecent



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.



DigSigCompareWordsAndFontsRecent

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

Return Value


Header File

DigSigHFT.h

Related Methods

DigSigComparePagesDigSigCompareWordsDigSigCompareWordsExDigSigCompareWordsRecent






DigSigCompareWordsEx

ASBool DigSigCompareWordsEx (PDDoc docA, PDDoc docB, DSCompareWordsParams params);

Description


N O T E : Supercedes DigSigCompareWords, DigSigCompareWordsAndFontsRecent, and DigSigCompareWordsRecent in Acrobat 6.0.

Parameters

Return Value


Header File

DigSigHFT.h

Related Methods

DigSigComparePagesExDigSigCompareWordsDigSigCompareWordsAndFontsRecentDigSigCompareWordsRecent



params A structure containing the comparison parameters.



DigSigCompareWordsRecent

ASBool DigSigCompareWordsRecent (PDDoc docA, PDDoc docB, ASBool iUseFonts);

Description



Parameters

Return Value


Header File

DigSigHFT.h

Related Methods

DigSigComparePagesDigSigCompareWordsDigSigCompareWordsAndFontsRecentDigSigCompareWordsEx






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

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

Related Methods

DigSigFileGetEOFDigSigFileSetPosDigSigFileReadDigSigOverwriteBytes

asFile The file containing the cosObj.

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

cosObj The cosString to be written.Does not write and returns 0 if there are any illegal characters in the string.

dsOverwriteType The type of overwrite to perform.● DSOverwriteStringHex (equivalent to calling DigSigOverwriteHexstring)

● DSOverwriteArray (equivalent to calling DigSigOverwriteIntArray)

● DSOverwriteStringBase64



DigSigOverwriteHexstringDigSigOverwriteIntArray



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

Return Value

A CosObj containing the new XObject form, or CosNewNull if unsuccessful

Header File

DigSigHFT.h

Related Methods

DigSigGetStdXObj

cosDoc The document containing the new object.

pBBoxRec A pointer to desired bounding box.

dsXObjType The type of object to create.



DigSigDeletedSig

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

Return Value

None

Header File

DigSigHFT.h

Related Methods

DigSigAddedSig DigSigDeletedSigEx

pdDoc The document that contains a signature field.



DigSigDeletedSigEx

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

Return Value

None

Header File

DigSigHFT.h

Related Methods

DigSigAddedSigEx DigSigDeletedSig

pdDoc The document that contained the signature field.

cosField The signature field that was deleted.



DigSigDocModifiedAfterSig

ASBool DigSigDocModifiedAfterSig (PDDoc doc, CosObj sigField);

Description

Tests whether a document has been modified since being signed with the specified signature.

Parameters

Return Value

ASBool true if the document has been modified, false otherwise.

Header File

DigSigHFT.h

Related Methods

None

pdDoc The document containing the signature field.

sigfield The signature field.



DigSigDoProperties

void DigSigDoProperties (AVDoc avDoc, CosObj sigField);

Description

Opens DigSig’s property dialog.

Parameters

Return Value

None

Header File

DigSigHFT.h

Related Methods

None

avDoc The document that contained the signature field.

sigField The signature field of the document.



DigSigDraw

void DigSigDraw (PDAnnot pdAnnot, AVPageView avPV, ASBool bIsSelected);

Description

Causes the signature to be redrawn.

Parameters

Return Value

None

Header File

DigSigHFT.h

Related Methods

DigSigHexToByteDigSigRightClick

pdAnnot The annotation the user clicked on or tabbed into

avPV The page view that contains the annotation

blsSelected true if the annotation is selected, false otherwise



DigSigEnumSignatures

void DigSigEnumSignatures (PDDoc pdDoc, DigSigEnumProc proc, void *clientData);

Description

Enumerates the signature fields (signed and unsigned) in the file.

Parameters

Return Value

None

Header File

DigSigHFT.h

Related Callbacks

DigSigEnumProc


proc The procedure to call once for each existing signature.

clientData Pointer to user-supplied data to pass to proc each time it is called.



DigSigFileGetEOF

ASInt32 DigSigFileGetEOF (ASFile asFile);

Description

Gets the number of bytes in an ASFile. Serves as a wrapper for the ASFileGetEOF method.

Parameters

Return Value

Number of bytes in the ASFile, or 0 if an error is encountered.

Header File

DigSigHFT.h

Related Methods

DigSigFileSetPosDigSigFileReadDigSigOverwriteIntArrayDigSigOverwriteHexstringDigSigOverwriteBytes

asFile The ASFile whose length is obtained.



DigSigFileRead

ASInt32 DigSigFileRead (ASFile asFile, char* p, ASInt32 count);

Description

Reads from an ASFile. This is a wrapper function for the ASFileRead method.

Parameters

Return Value

Number of bytes read, or 0 if unsuccessful.

Header File

DigSigHFT.h

Related Methods

DigSigFileGetEOFDigSigFileSetPosDigSigOverwriteIntArrayDigSigOverwriteHexstringDigSigOverwriteBytes

asFile The ASFile to read.

p Pointer to a buffer.

count Number of bytes to read into the buffer.



DigSigFileSetPos

void DigSigFileSetPos (ASFile asFile, ASInt32 pos);

Description

Reopens an ASFile for reading and sets the file position.

Parameters

Return Value

None

Header File

DigSigHFT.h

Related Methods

DigSigFileGetEOFDigSigFileReadDigSigOverwriteIntArrayDigSigOverwriteHexstringDigSigOverwriteBytes

asFile The ASFile to position.

pos The byte offset to a position in asFile



DigSigFinishSigRefDict

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

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

Related Methods

DigSigClearSigRefDictDigSigCommitSigRefDictDigSigNewSigRefDictDigSigVerifySigRefDict

transformMethod The transform method used to calculate the digest. It must match originally specified in DigSigNewSigRefDict


refDict The reference dictionary returned from the call to DigSigCommitSigRefDict

errParams A structure containing information about an exception.



DigSigGetDocAuthorSignature

CosObj DigSigGetDocAuthorSignature (PDDoc doc);

Description

Gets the author signature for a document as a Cos object.

Parameters

Return Value

The CosObj containing the author signature.

Header File

DigSigHFT.h

Related Methods

DigSigGetDocMDPSetting

doc The document for which the author signature is obtained.




DSMDPType DigSigGetDocMDPSetting (PDDoc doc);

Description

Gets the MDP setting for the author signature for the specified document.

Parameters

Return Value

The MDP setting of the document’s author signature, or kDSMDPNone if there is no author signature.

Header File

DigSigHFT.h

Related Methods


doc The document for which the MDP setting is obtained.



DigSigGetStdXObj

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

Return Value

Returns the CosObj of the desired type, or CosNewNull if unsuccessful.

Header File

DigSigHFT.h

Related Methods

None


dsXObjType The type of object to get.



DigSigGetUbiquitySignature

CosObj DigSigGetUbiquitySignature (PDDoc doc);

Description

Gets the Reader Extensions signature for a document as a Cos object.

Parameters

Return Value

The CosObj containing the Reader Extensions signature.

Header File

DigSigHFT.h

Related Methods


doc The document for which the Reader Extensions signature is obtained.



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

Return Value

The unique field name string.

Header File

DigSigHFT.h

Related Methods

None

cosDoc The document that will contain the new field.



DigSigHexToByte

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 <412f> 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

Return Value

None

Header File

DigSigHFT.h

Related Methods

DigSigByteToHex

hexP Pointer to the hex string. The string must begin with “<“ and end with “>”, optionally followed by a NULL character.

byteP (Filled by the method) Pointer to an output buffer to hold the byte string. Must be at least (length - 2) / 2 bytes long.

length Length of the hex string in bytes, not including any trailing NULL character, that is, strlen(hexP).



DigSigIsDocSigned

ASBool DigSigIsDocSigned (PDDoc doc);

Description

Tests whether a document is signed.

Parameters

Return Value

true if the document is signed, false otherwise.

Header File

DigSigHFT.h

Related Methods

DigSigIsSigSigned

doc The document that is tested.



DigSigIsSigSigned

ASBool DigSigIsSigSigned (PDDoc doc, CosObj sigField);

Description

Tests whether a particular signature field in a document is signed.

Parameters

Return Value

true if the signature field is signed, false otherwise.

Header File

DigSigHFT.h

Related Methods

DigSigIsDocSigned

doc The document that contains the signature field.

sigField The signature field that is tested.



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 <CR>, this method selects the annotation.

Parameters

Return Value

None

Header File

DigSigHFT.h

Related Methods

DigSigDrawDigSigClickDigSigRightClick

pdAnnot The annotation the user clicked on.

avpv The current page view.

nKey The key pressed by the user.




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

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

Related Methods

None

asFile The file over which the hash function is calculated.

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

md5hash A pointer to a buffer that receives the 16-byte hash value.



DigSigNewSigRefDict

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

Return Value

kDSTrue on success; kDSFalse on parameter errors.

kDSException means an exception occurred; information can be found in errParams.

Header File

DigSigHFT.h

Related Methods

DigSigClearSigRefDictDigSigCommitSigRefDictDigSigFinishSigRefDictDigSigVerifySigRefDict

refParams A structure containing information about the signature reference dictionary; must be filled in by the caller.

errParams (Filled by the method) A structure containing information about exceptions that occurred.



DigSigOverwriteBytes

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 O T E : To overwrite a text string entry, such as /Reason, the string must be in the format "< xxx >", not "xxx".

Parameters

Return Value

The number of bytes written, or 0 if unsuccessful.

Header File

DigSigHFT.h

Related Methods

DigSigCosObjOverwriteDigSigFileGetEOFDigSigFileSetPosDigSigFileReadDigSigOverwriteIntArrayDigSigOverwriteHexstring

asFile The ASFile to write to.

digSigOffset A structure specifying the byte position and size to overwrite.

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



DigSigOverwriteHexstring

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

Return Value

The number of bytes written.

Header File

DigSigHFT.h

Related Methods

DigSigCosObjOverwriteDigSigFileGetEOFDigSigFileSetPosDigSigFileReadDigSigOverwriteIntArrayDigSigOverwriteBytes


digSigOffset A structure specifying the byte position and size to overwrite.● 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.

cosObj The Cos string to be written.



DigSigOverwriteIntArray

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

Return Value

The number of bytes written.

Header File

DigSigHFT.h

Related Methods

DigSigCosObjOverwriteDigSigFileGetEOFDigSigFileSetPosDigSigFileReadDigSigOverwriteHexstringDigSigOverwriteBytes


digSigOffset A structure specifying the byte position and size to overwrite.● 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.

cosObj The Cos string to be written.



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

Return Value

None

Header File

DigSigHFT.h

Related Methods

DigSigUnregisterFilter

owner The handler plug-in identifier, assigned on initialization.

digSigHandler A structure specifying the name of the filter and the functions to call to create and validate signatures.



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

Return Value

The observer identifier, which must be provided to DigSigUnregisterObserver.

Header File

DigSigHFT.h

Related Methods

DigSigUnregisterObserver

notificationID The type of event for which to register a callback.

notifyProc The procedure to call when a field change, request, or success event occurs.

notifyFailure The procedure to call when a failure event occurs.

clientData A pointer to client-supplied data to pass to the callback procedure.



DigSigRightClick

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

Return Value

None

Header File

DigSigHFT.h

Related Methods

DigSigDrawDigSigHexToByteDigSigClick

pdAnnot The annotation the user clicked on.

avPV The page view the annotation is within.

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

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


nClicks The number of clicks.



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

Return Value

None

Header File

DigSigHFT.h

Related Methods

None

pdDoc The document that contained the signature field.

sigField The signature field of the document.



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

Return Value

None

Header File

DigSigHFT.h

Related Methods

None

pdDoc The document to be signed.

sigField The field to be signed or CosNull.

filtrKey The signing method to use.



DigSigUnregisterFilter

void DigSigUnregisterFilter (DigSigHandler digSigHandler);

Description

Unregisters a signing method plug-in. The caller should deallocate the DigSigHandler object after making this call.

Parameters

Return Value

None

Header File

DigSigHFT.h

Related Methods


digSigHandler A structure specifying the name of the filter and the functions to call to create and validate signatures.



DigSigUnregisterObserver

void DigSigUnregisterObserver (DSNotificationType notificationID, ASInt32 observerID);

Description

Unregisters an event interest from the notification server.

Parameters

Return Value

None

Header File

DigSigHFT.h

Related Methods


notificationID The event for which an interest has been registered, as specified in DigSigRegisterObserver.

observerID The observer identifier as returned by DigSigRegisterObserver.



DigSigUpdatePanel

void DigSigUpdatePanel (PDDoc pdDoc);

Description

Updates the signature panel, if any, associated with pdDoc.

Parameters

Return Value

None

Header File

DigSigHFT.h

Related Methods

None

pdDoc The document whose panel is to be updated.



DigSigVerifySig

DSValidState DigSigVerifySig (PDDoc pdDoc, CosObj sigField, ASBool bUI);

Description

Verifies a digital signature.

Parameters

Return Value

The validity state that results from verification.

Header File

DigSigHFT.h

Related Methods

DigSigClearSig

pdDoc The document.

sigField The signature field to verify.

bUI When true, can bring up the user-interface dialogs if needed.



DigSigVerifySigRefDict

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

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

Related Methods

DigSigClearSigRefDictDigSigCommitSigRefDictDigSigFinishSigRefDictDigSigNewSigRefDict

transformMethod The transform method used to calculate the signature. It must match the one stored in refDict


refDict The signature reference dictionary that was returned from a call to DigSigCommitSigRefDict

errParams A structure containing information about an exception.


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

Return Value

true to continue enumeration, false otherwise.

Header File

DigSigHFT.h

Related Methods

DigSigEnumSignatures


sigField The signature field.


Digital Signature Callbacks6


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

Return Value

true if the handler can validate the field signature, false otherwise.

Header File

DigSigHFT.h

Related Methods

DigSigVerifySig


sigField The signature field.

sigAnnot The signature annotation that is being verified (usually equivalent to sigField).

filter The name by which DigSig knows this handler. This is not necessarily the value of /Filter.


Digital Signature Callbacks 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

Return Value

None.

Header File

DigSigHFT.h

pdDoc The document being signed.

sigField Signature field.

sigAnnot Cos object of the signature annotation.



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

Return Value

true if the signature was successfully placed in pdDoc, false otherwise.

Header File

DigSigHFT.h

Related Callbacks

DSFinishSignProc DSNewSigDataProc


sigData Signature data, as defined by the specific signature plug-in.



offsetArray (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



DSDefaultValueProc

ACCB1 void ACCB2 DSDefaultValueProc (PDDoc pdDoc, CosObj sigField, CosObj sigAnnot);

Description

N O T E : 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.

Parameters

Return Value

None

Header File

DigSigHFT.h






DSDocCloseProc

ACCB1 void ACCB2 DSDocCloseProc (PDDoc pdDoc);

Description

Callback for DigSigHandler. Called when a new document is closed.

Parameters

Return Value

None

Header File

DigSigHFT.h

Related Callbacks

DSDocOpenProc

pdDoc The document being closed.



DSDocOpenProc

ACCB1 void ACCB2* DSDocOpenProc (PDDoc pdDoc);

Description

Callback for DigSigHandler. Called when a new document is opened.

Parameters

Return Value

None

Header File

DigSigHFT.h

Related Callbacks

DSDocCloseProc

pdDoc The document that has been opened.



DSFinishSignProc

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

Return Value

true if processing successful, false otherwise.

Header File

DigSigHFT.h

Related Callbacks

DSClearSigProc

Related Methods

DigSigOverwriteHexstring DigSigOverwriteIntArray





offsetArray (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



DSFreeSigDataProc

ACCB1 void ACCB2 DSFreeSigDataProc (void* sigData);

Description

Callback for DigSigHandler. Frees signature data.

Parameters

Return Value

None

Header File

DigSigHFT.h

sigData Signature data, as defined by the specific signature plug-in. The handler should check to see if sigData is NULL.



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

Return Value

The property value, true or false.

Header File

DigSigHFT.h

filter The name (filterKey value) of the handler from which the property is obtained.

property The property whose value is obtained.



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

Return Value

An ASCab object containing the properties. For a list of properties, see DigSigHFT.h.

Header File

DigSigHFT.h




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.



DSGetStatusTextProc

ASText DSGetStatusTextProc (PDDoc pdDoc, CosObj sigField, CosObj sigAnnot);

Description

Return a string describing the status of the signature. Must be PDDocEncoding or unicode, where unicode strings must start with 0xFE, 0xFF.

N O T E : Superceded by DSGetSigPropProc in Acrobat 6.0, which provides better granularity for signature status.

Parameters

Return Value

None.

Header File

DigSigHFT.h






DSGetValidStateProc

ACCB1 DSValidState ACCB2 DSGetValidStateProc (PDDoc pdDoc, CosObj sigField, CosObj sigAnnot);

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

Enumerations

Return Value

Validation state.

Header File

DigSigHFT.h

Related Methods

DigSigUpdatePanel




DSSigBlank The signature field is unsigned.

DSSigUnknown The signature field is signed but not validated.

DSSigInValid The signature field is signed but invalid.

DSSigValid The signature field is signed and valid.

DSSigDoubleChecked The signature field is signed and double-checked valid.



DSNewSigDataProc

ACCB1 ASBool ACCB2 DSNewSigDataProc (PDDoc pdDoc, DigSigBBox bb, void** sigData, CosObj sigField, CosObj sigAnnot);

Description

N O T E : 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.

Parameters

Return Value

true if signature data gathered, false if canceled.

Header File

DigSigHFT.h

Related Callbacks

DSClearSigProc DSNewSigDataWithParamsProcDSFinishSignProc DSFreeSigDataProc


bb Signature annotation bounding box.






DSNewSigDataWithParamsProc

ACCB1 DSSaveType ACCB2 DSNewSigDataProc (DigSigNewSigDataParams sigParams, void** sigData);

Description

N O T E : 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.

Parameters

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

Related Callbacks

DSCommitSignProcDSNewSigDataProcDSFinishSignProc DSFreeSigDataProc DSSigDataGetErrorTextProc

sigParams The structure containing signing parameters.

sigData (Filled by the method) Signature data, as defined by the specific signature plug-in.



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

Return Value

None

Header File

DigSigHFT.h

Related Callbacks

DSNotificationFailureProc

Related Methods


info Pointer to a DSNotifyParams structure containing information about the event.




DSNotificationFailureProc

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

Return Value

None

Header File

DigSigHFT.h

Related Callbacks

DSNotificationProc

Related Methods


error The error code for the error that occured.

info Pointer to a DSNotifyParams structure containing information about the event.




DSPropertiesProc

ACCB1 void ACCB2 DSPropertiesProc (PDDoc pdDoc, CosObj sigField, CosObj sigAnnot);

Description

N O T E : 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.

Parameters

Return Value

None

Header File

DigSigHFT.h

Related Methods

DigSigUpdatePanel






DSPropertiesExProc

ACCB1 void ACCB2 DSPropertiesExProc (PDDoc pdDoc, CosObj sigField, CosObj sigAnnot, ASAtom handlerName, ESObject sigEngine);

Description

N O T E : 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.

Parameters

Return Value

None

Header File

DigSigHFT.h

Related Methods

DigSigUpdatePanel




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

sigEngine Used internally.



DSReValidateSigProc

ACCB1 void ACCB2 DSReValidateSigProc (PDDoc pdDoc, CosObj sigField, CosObj sigAnnot);

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

Return Value

None

Header File

DigSigHFT.h

Related Callbacks

DSUnValidateSigProc






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

Return Value

The error string as an ASText.

Header File

DigSigHFT.h

Related Callbacks

DSFreeSigDataProcDSNewSigDataWithParamsProc

sigData A pointer to the signature for which the error string is obtained.



DSUnValidateSigProc

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

Return Value

None

Header File

DigSigHFT.h

Related Callbacks

DSValidateSigProc DSReValidateSigProc

Related Methods

DigSigGetStdXObj

Related Methods

DigSigFileGetEOF DigSigMD5ByteRange DigSigFileRead DigSigFileSetPos






DSValidateSigProc

ACCB1 DSValidState ACCB2 DSValidateSigProc (PDDoc pdDoc, CosObj sigField, CosObj sigAnnot);

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

Return Value

Validation state.

Header File

DigSigHFT.h

Related Callbacks

DSUnValidateSigProc DSReValidateSigProc

Related Methods

DigSigFileGetEOF DigSigMD5ByteRange DigSigFileRead DigSigFileSetPos





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

Header File

DigSigHFT.h

Related Callbacks

DSNewSigDataProc

bbwidth The width of the signature bounding box.

bbHeight The height of the signature bounding box.

Digital Signature Declarations7


DigSigHandler

typedef struct _t_DigSigHandlerRec* DigSigHandler;typedef struct _t_DigSigHandlerRec {ASSize_t size;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.


Digital Signature Declarations 7

Members

size Size of the data structure. Must be set to sizeof(DigSigHandlerRec).

uiName Language-dependent name to show for signature type selection.

filterKey The value of the Filter key in the signature dictionary.

canBindSign true if this signature type can do no-appearance signatures, false otherwise.

canEncrypt true if this signature type can do encrypt-and-sign, false otherwise.

dsDocOpen Called when a new document is opened.

dsDocClose Called when a new document is closed.

dsDefaultValue Called when a new signature field is created.

dsNewSigData Called to gather signature or cancel.

dsCommitSign Called to put signature into doc or cancel.

dsFinishSign Called to calculate checksum and overwrite.

dsFreeSigData Called to free signature data.

dsGetValidState Called by sig panel display.

dsProperties Called by sig panel display.

dsUnValidateSig Called to change AP back to unvalidated.

dsReValidateSig Called to change AP back to whatever it was.

dsClearSig Notification that signature has been cleared.

dsStatusText Called to get a string describing status.

dsNewSigDataEx Used internally in Acrobat 5.0. Superceded in Acrobat 6.0 by dsNewSigDataWithParams.

dsValidateSigExdsGetSigInfo

Used internally by PubSec.

dsNewSigEngine Used internally by EScript in Acrobat 5.0. No longer used.



Header File

DigSigHFT.h

Related Methods


dsSigDataGetErrorText Called to get a descriptive string for an error during new, commit, or free steps.

dsNewSigDataWithParams Called to create new signature data to be used by Commit and Finish. Supercedes ds

dsPropertiesEx Called to show the signature properties dialog for the signature.

dsCosDocSigSigndsCosDocSigValidatedsDataBufferSigSigndsDataBufferSigValidate

For internal use only.

dsCanValidate Called to determine whether handler can validate a PDDoc field signature.

dsGetSigSeedValuedsSetSigSeedValue

Used internally by PubSec.

dsGetBoolProperty Called to test whether your handler supports specific functionality.

dsGetSigProp Called to get an ASCab containing signature properties to be used in the UI.



DigSigNewSigDataParams

typedef struct _t_DigSigNewSigDataParamsRec {ASSize_t size;PDDoc pdDoc;CosObj sigField;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 Size of the data structure. Must be set to sizeof(DigSigNewSigDataParamsRec).

pdDoc The PDF document that is being signed.

sigField Signature form field that is being signed.

sigAnnot Signature annotation that is being signed (usually equivalent to sigField).

bb Bounding box of signature appearance.

filter Name of the selected handler to use when signing.

esSigEngineesSigParamsesErrorText

Used internally.

bUI If true, prompt to sign, otherwise silent. (Can be true with Escript.)

bDocAuthSig When true, signing a document author signature.



Header File

DigSigHFT.h

Related Callbacks

DSNewSigDataWithParamsProc

legalPDFDict Legal PDF scrubber warnings, populated only when signing a document author signature.

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



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

Header File

DigSigHFT.h

Related Callbacks

DSClearSigProc DSFinishSignProc

Related Methods

DigSigCosObjOverwriteDigSigOverwriteBytes DigSigOverwriteHexstringDigSigOverwriteIntArray

cosObj The CosObj whose byte offset/length is desired.

byteOffset Byte offset in saved PDF file.

byteLength Length in saved PDF file.



DSAPCreateLayeredStreamExParams

typedef struct _t_DSAPCreateLayeredStreamExParams{

CosDoc cosDoc;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


XObjects A pointer to an array of XObjects for the appearance layers.

layerMatrices A pointer to an array of positions corresponding to the layers in XObjects.

numXObjects The size of the XObjects array.

layerNNum The layer number for the optional validity state layer.

border The border from AFPDWidgetGetBorder.



cBorder The color of the border.

cBackGnd color of the background.

width The width of the new stream object.

height The height of the new stream object.

pdr The rotational parameter from AFPDWidgerGetRotation.

layerFlags An array of flag values corresponding to the layers specified by XObject. A value of true means that the corresponding layer is displayed.



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

Header File

DigSigHFT.h

Related Methods

DSAPCreateCompositeTextXObj

next Next list entry, or NULL if last entry.

heightRation Ration of the text height to the overall height of the bounding box. 0x00010000 is 100%

text The text to render in this object. The caller owns this memory.



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 Next list entry.

xobj If not null, use this Xobject as entry.

rect Rect relative to bbox in which to render object.

text If not empty, render this string (can contain new lines).

textLen Text length.

textSize Font size; 0 for automatic.

xjustify Justification of xobj (not all options supported).

yjustify Justification of xobj (not all options supported).

scale Scale Xobject within rect.

bMerge If true and xobj is Subtype Xobject then xobj is merged up.

bDestroy if true, destroy xobj after merge.



Header File

DigSigHFT.h

Related Methods




DSComparePagesParams

typedef struct _t_DSComparePagesParamsRec {ASSize_t size;ASInt32 sensitivityLevel;

} DSComparePagesParamsRec, *DSComparePagesParams;

Description

Parameters for page comparison.

Members

Header File

DigSigHFT.h

Related Methods

DigSigComparePagesEx

size Size of the data structure. Must be set to sizeof(DSComparePagesParamsRec).

sensitivityLevel 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 DPI1: 36 DPI2: 18 DPI



DSCompareWordsParams

typedef struct _t_DSCompareWordsParamsRec {ASSize_t size;ASBool useFont;

} DSCompareWordsParamsRec, *DSCompareWordsParams;

Description

Parameters for page comparison.

Members

Header File

DigSigHFT.h

Related Methods

DigSigCompareWordsEx

size Size of the data structure. Must be set to sizeof(DSCompareWordsParamsRec).

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



DSHandlerProperty

typedef enum {kDSHandlerCanDocAuthSign=0, kDSHandlerCanDocPDDocSignVisible, kDSHandlerEScriptAware, kDSHandlerPropEnumSize

} DSHandlerProperty;

Description

Boolean properties of a DigSigHandler, obtained with DSGetBoolPropertyProc, that show whether the handler supports specific functionality.

Values

Related Callbacks

DSGetBoolPropertyProc

kDSHandlerCanDocAuthSign When true, the handler supports author signatures.

kDSHandlerCanDocPDDocSignVisible When true, the handler supports ordinary visible signatures.

kDSHandlerEScriptAware When true, the handler supports EScript.



DSMDPType

typedef enum {kDSMDPNone = -1, kDSMDPAllowAll=0, kDSMDPAllowNone, kDSMDPDefault, kDSMDPCommentsAndDefault, kDSMDPEnumSize

} DSMDPType;

Description

The modification detection and prevention (MDP) value for an author signature.

Members

Header File

DigSigHFT.h

Related Methods


kDSMDPNone No MDP, or the document does not have an author signature.

kDSMDPAllowAll Allow any changes (this disables the MDP feature).

kDSMDPAllowNone Allow no changes.

kDSMDPDefault Only allow 'natural' changes ( form field fill-in, page spawning).

kDSMDPCommentsAndDefault Allow all comment types, edit, modify, and delete operationa, in addition to default changes.



DSNotificationType

typedef enum { 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 Signature field is added.

DSSigDeleted Signature field is deleted.

DSWillSign A signature is requested. (That is, the notification procedure is invoked before the signature is applied.)

DSDidSign A signature is created. (That is, the notification procedure is invoked when signing succeeds.)

DSFailSign A signature request fails. (That is, the notification procedure is invoked when signing fails.)

DSWillVerify A signature verification is requested.

DSDidVerify A signature verification succeeds.

DSFailVerify A signature verification request fails.

DSWillClear The clearing of a signature is requested.

DSDidClear The clearing of a signature succeeds.

DSFailClear The clearing of a signature fails.



Header File

DigSigHFT.h

Related Methods




DSNotifyParams

typedef struct _t_DSNtfyParamsRec {ASSize_t size; DSNotificationType notificationID; PDDoc pdDoc; CosDoc cosDoc;CosObj sigField;CosObj sigDict;

} 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

Header File

DigSigHFT.h

Related Callbacks

DSNotificationProcDSNotificationFailureProc

Related Methods


size Size of the data structure. Must be set to sizeof(DSNotifyParamsRec).

notificationID The event that occurred.

pdDoc The PDF document for which the event occurred.

cosDoc The Cos document containing the object for which the event occurred.

sigField The signature field for which the event occurred.

sigDict The signature dictionary (used only for the events DSDidSign and DSDidClear).



DSOverwriteType

typedef enum {DSOverwriteStringHex=0, DSOverwriteStringBase64, DSOverwriteArray, DSOverwriteEnumSize

} DSOverwriteType;

Description

Constant values that determine the type of Cos object overwrite to be performed.

Members

Header File

DigSigHFT.h

Related Methods

DigSigCosObjOverwrite

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 .



DSQuadding

typedef enum {DSLeftQ = 0,DSCenterQ,DSRightQ

} DSQuadding;

Description

Justification of XObjects.

Members

Header File

DigSigHFT.h

Related Methods


DSLeftQ left justification.

DSCenterQ center justification

DSRightQ right justification



DSSigRefDictErrParams

typedef struct _t_DSSigRefDictErrParamsRec {ASSize_t size; DSSigRefErrCode errCode; ASText errText;

} DSSigRefDictErrParamsRec, *DSSigRefDictErrParams;

Description

A structure that contains information about exceptions that occurred in signature reference dictionary procedures.

Members

Header File

DigSigHFT.h

Related Methods

DigSigFinishSigRefDict DigSigNewSigRefDictDigSigVerifySigRefDict

size The size of this structure.

errCode The exception code.

errText Text associated with the error code. If errCode is kDSSigRefErrMissingPlugin, the name of a software module. Must point to an initialized ASText object.



DSSigRefDictParams

typedef struct _t_DSSigRefDictParamsRec {ASSize_t size; CosDoc cosDoc; CosObj rootObj; CosObj sigDict; 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

Header File

DigSigHFT.h

Related Methods

DigSigNewSigRefDict

size Size of the data structure. Must be set to sizeof(DSSigRefDictParamsRec).

cosDoc The document containing the object to be signed.

rootObj The root object to be signed.

sigDict The signature dictionary that this reference dictionary will be part of.

transformMethod The transform method name. Possible values are DocMDP, FieldMDP, UR and Identity.

transformParams The transform parameters, which are specific to each transform method.

bIndirect true if the dictionary should be indirect, false if it should be direct.



DSSigRefErrCode

typedef enum {kDSSigRefErrNone=0,kDSSigRefErrMissingPlugin,kDSSigRefErrNewVersion,kDSSigRefErrOldVersion,kDSSigRefErrEnumSize

} DSSigRefErrCode;

Description

Error constants for signature reference dictionary procedures.

Values

Header File

DigSigHFT.h

Related Methods

DigSigFinishSigRefDict DigSigNewSigRefDictDigSigVerifySigRefDict

kDSSigRefErrMissingPlugin Missing required plug-in or software module. Software module is named by errText in DSSigRefDictErrParams.

kDSSigRefErrNewVersion New unsupported version of signature.

kDSSigRefErrOldVersion Old unsupported version of signature.



DSValidState

typedef enum {DSSigBlank=0,DSSigUnknown,DSSigInvalid,DSSigValid,DSSigDoubleChecked,DSSigValidStateEnumSize

} DSValidState;

Description

A validity state constant for a signature field, resulting from verification.

Values

Header File

DigSigHFT.h

Related Methods

DigSigVerifySig

Related Callbacks

DSGetValidStateProcDSValidateSigProc

DSSigBlank Signature field is unsigned.

DSSigUnknown Signature field is signed, but not validated.

DSSigInvalid Signature field is signed, but validation failed.

DSSigValid Signature field is signed and valid.

DSSigDoubleChecked Signature field is signed and double-checked valid.



DSXObjType

typedef enum {DSBlankXObj, DSUnknownXObj, DSInvalidXObj, DSValidXObj, DSDoubleCheckedXObj

} DSXObjType;

Description

Structure describing the appearance of a digital signature.

Members

Header File

DigSigHFT.h

Related Callbacks

DSUnValidateSigProc

Related Methods

DigSigGetStdXObj

DSBlankXObj Blank appearance

DSUnknownXObj Signed but not validated appearance.

DSInvalidXObj Signed and failed validate appearance.

DSValidXObj Signed and valid, but identity not verified.

DSDoubleCheckedXObj Signed and valid and identity verified.


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.

Digital Signature’s Use of Core API Objects8


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.