diff options
Diffstat (limited to 'Adobe_SigHandler/Adobe.PDF-AS-SigHandler/sources/import/API/PubSecHFTProcs.h')
| -rw-r--r-- | Adobe_SigHandler/Adobe.PDF-AS-SigHandler/sources/import/API/PubSecHFTProcs.h | 577 |
1 files changed, 577 insertions, 0 deletions
diff --git a/Adobe_SigHandler/Adobe.PDF-AS-SigHandler/sources/import/API/PubSecHFTProcs.h b/Adobe_SigHandler/Adobe.PDF-AS-SigHandler/sources/import/API/PubSecHFTProcs.h new file mode 100644 index 0000000..84c9650 --- /dev/null +++ b/Adobe_SigHandler/Adobe.PDF-AS-SigHandler/sources/import/API/PubSecHFTProcs.h @@ -0,0 +1,577 @@ +/*************************************************************************
+ * PubSecHFTProcs.h
+ *
+ * Copyright (c) 2007 Adobe Systems Inc. All Rights Reserved.
+ *
+ * NOTICE: All information contained herein is, and remains the
+ * property of Adobe Systems Incorporated and its suppliers, if any.
+ * The intellectual and technical concepts contained herein are
+ * proprietary to Adobe Systems Incorporated and its suppliers and may
+ * be covered by U.S. and Foreign Patents, patents in process, and are
+ * protected by trade secret or copyright law. Adobe permits you to
+ * use, modify, and distribute this file in accordance with the terms
+ * of the Adobe license agreement accompanying it. If you have
+ * received this file from a source other than Adobe, then your use,
+ * modification, or distribution of it requires the prior written
+ * permission of Adobe.
+ *
+ * Description:
+ *
+ * Public key security interface for Acrobat public-key security
+ * handlers. Handlers can register as PubSec handlers to provide
+ * crypto services for private key signing, for signature validation,
+ * as a crypto source for decrypting using private keys, and as a
+ * directory source.
+ *
+ * Handlers can also call back into the PubSecHFT for various
+ * services, including a signature appearance handler and a trusted
+ * address book.
+ *
+ * Update History: (most recent first)
+ * 11-May-2007 -- Created from PubSecHFT.h for Acrobat 9.0
+ ************************************************************************/
+/************************************************************************************
+ * PubSecHFT - Prototype declarations
+ ***********************************************************************************/
+
+/* HFTBeginProto - do not alter/remove this line! */
+
+
+/**
+ Registers a handler with the PubSec HFT. The caller retains
+ ownership of the PubSecHandlerRec.
+ @param owner The handler's plug-in ExtensionID, assigned
+ at initialization.
+ @param psHandler The handler structure containing the
+ handler methods to register.
+ @return <code>true</code> if successful, <code>false</code> otherwise.
+ @see PSUnregisterHandler
+*/
+PIPROC(ASBool, PSRegisterHandler,
+ ( ExtensionID owner, PubSecHandler psHandler ), owner, psHandler)
+
+
+/**
+ Unregisters a handler from the PubSec HFT. This does not
+ destroy the handler; the caller owns the PubSecHandlerRec.
+
+ @param psHandler The handler to unregister.
+ @return <code>true</code> if successful, <code>false</code> otherwise.
+ @see PSRegisterHandler
+*/
+PIPROC(void, PSUnregisterHandler,
+ ( PubSecHandler psHandler ), psHandler)
+
+
+/*************************************************************************
+ * Doc Cache methods. PubSec keeps a list of all encrypted documents
+ * that are open. For security reasons handlers will want these
+ * documents to all be closed when a handler releases access to
+ * critical resources, for example when logging out.
+ ************************************************************************/
+
+/**
+ Returns the number of encrypted documents associated with
+ a PubSec engine. It 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.
+ @param engine The engine for which the encrypted docs
+ are counted.
+ @param outNeedSave (Filled by the method) A pointer to
+ the number of encrypted documents associated with the engine
+ that need to be saved.
+ @param 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.
+ @see PSCloseEncryptedDocs
+*/
+PIPROC(void, PSCountEncryptedDocs,
+ ( PubSecEngine engine, ASUns32 *outNeedSave, ASUns32 *outCanClose ), engine, outNeedSave, outCanClose )
+
+
+/**
+ Closes all encrypted documents associated with a PubSec
+ engine, regardless of whether they need to be saved.
+ Use PSCountEncryptedDocs() to determine if there are any documents
+ that will need to be opened or saved.
+
+ <p>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. </p>
+
+ @param engine The engine for which the encrypted documents
+ are closed.
+ @return <code>true</code> if successful, <code>false</code> otherwise.
+ @see PSCountEncryptedDocs
+*/
+PIPROC(ASBool, PSCloseEncryptedDocs, ( PubSecEngine engine ), engine)
+
+PIPROC(ASBool, PSSigValidatePDDocSigField, ( PSSigPDDocParams docParams ), docParams)
+
+/*************************************************************************
+ * Signature operations
+ ************************************************************************/
+
+/**
+ 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. It does not bring up any user interface.
+
+ <p>A return value of <code>true</code> 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. </p>
+ @param docParams The validation parameters.
+ @return <code>true</code> if the validation was successfully performed, <code>false</code>
+ otherwise.
+
+ @note This method cannot validate a signature whose cache
+ has not been updated or is <code>NULL</code>. In this case, use DigSigVerifySig().
+*/
+
+/**
+ Gets bytes of data to digest when signing or verifying,
+ in chunks of a specified size. It continues getting data chunks
+ until all of the data in the data buffer has been returned.
+
+ <p>A handler will use this call when computing its own data
+ digest, to get the next blob of bytes to digest. The <code>dataBuffer</code>
+ 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. </p>
+
+ <p>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. </p>
+
+ <p>PSDataBufferDigest() uses this method when computing the digest for the data. </p>
+ @param dataBuffer The buffer containing the data.
+ @param maxSize The maximum number of bytes to return in
+ the return buffer.
+ @param pReturnBuffer (Filled by the method) A pointer
+ to the buffer containing the current bytes to be processed.
+ If it is <code>NULL</code>, an error occurred and you should abort the enumeration.
+
+ @param pReturnSize (Filled by the method) A pointer to
+ the size in bytes of the return buffer. When it is <code>0</code>, do not process
+ the return buffer, but continue enumerating until the method
+ returns <code>false</code>. It is always less than <code>maxSize</code>.
+ @return <code>true</code> as long as there is more data to process, <code>false</code> when
+ the end of the buffer is reached.
+ @see PSDataBufferReset
+ @see PSDataBufferDigest
+*/
+PIPROC(ASBool, PSDataBufferEnum,
+ ( PSDataBuffer dataBuffer, ASInt32 maxSize, ASUns8 **pReturnBuffer, ASInt32 *pReturnSize ),
+ dataBuffer, maxSize, pReturnBuffer, pReturnSize )
+
+
+/**
+ 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.
+ @param dataBuffer The buffer containing the data.
+ @param digestValue (Filled by the method) A pointer to
+ the digest value. The buffer must large enough for the requested
+ digest method:
+ <ul>
+ <li>For an MD5 digest, it must be at least 16 bytes.</li>
+ <li>For an SHA-1 digest, it must be at least 20 bytes.</li>
+ </ul>
+ @param digestMethod The method to use to compute the digest.
+ @return <code>true</code> if successful, <code>false</code> otherwise.
+ @see PSDataBufferReset
+ @see PSDataBufferEnum
+*/
+PIPROC(ASBool, PSDataBufferDigest,
+ ( PSDataBuffer dataBuffer, ASUns8* digestValue, DSDigestMethod digestMethod ),
+ dataBuffer, digestValue, digestMethod )
+
+/**
+ Acquires the DSAP file and opens it, if it has not already
+ been acquired.
+
+ <p>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. </p>
+
+ @param bResolveProblems When it is <code>true</code>, if there are problems
+ trying to open the file, PubSec opens a user interface that gives a
+ user the option to delete the corrupted file.
+ @param bCreate When it is <code>true</code>, if the file does not exist it
+ is created. It is normally <code>true</code>.
+ @return <code>true</code> if the file was acquired and opened, <code>false</code> otherwise.
+
+ @see DSAPFileRelease
+*/
+PIPROC(ASBool, DSAPFileAcquire, ( const ASBool bResolveProblems, const ASBool bCreate ), bResolveProblems, bCreate )
+
+
+/**
+ Closes the digital signature appearance (DSAP) file.
+ @see DSAPFileAcquire
+ @see DSAPFileSave
+*/
+PIPROC(void, DSAPFileRelease, (void), )
+
+
+/**
+ Saves the DSAP file if it is dirty, leaving it open.
+ @see DSAPFileRelease
+*/
+PIPROC(void, DSAPFileSave,(void), )
+
+/**
+ Gets the number of configured signature appearance entries
+ in the DSAP file,
+ @return The number of configured AP entries.
+ @see DSAPFileCanDeleteNthEntry
+*/
+PIPROC(ASInt32, DSAPFileGetCount, (void), )
+
+/**
+ Tests whether a signature appearance entry at a specified
+ index in the DSAP file can be edited or is read-only.
+ @param index The position of the entry to test. The first
+ entry is at index <code>0</code>. A negative value gets the default entry.
+ @return <code>true</code> if the entry is editable, <code>false</code> otherwise.
+ @see DSAPFileGetCount
+ @see DSAPFileRemoveNthEntry
+*/
+PIPROC(ASBool, DSAPFileCanDeleteNthEntry, ( const ASInt32 index ), index)
+
+/**
+ 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.
+ @param index The position of the entry whose name to obtain.
+ The first entry is at index <code>0</code>. A negative value gets the
+ default entry.
+ @return A copy of the name as an ASText object.
+ @see DSAPFileGetCount
+ Closes the digital signature appearance (DSAP) file.
+ @see DSAPFileAcquire
+ @see DSAPFileSave
+*/
+PIPROC(ASText, DSAPFileGetNewNthName, ( const ASInt32 index ), index)
+
+/**
+ Deletes the specified signature appearance entry from the
+ DSAP file.
+ @param index The position of the entry to remove. The
+ first entry is at index <code>0</code>. A negative value gets the default
+ entry.
+ @return <code>true</code> if successful, <code>false</code> otherwise.
+ @see DSAPFileCanDeleteNthEntry
+ @see DSAPFileGetCount
+*/
+PIPROC(ASBool, DSAPFileRemoveNthEntry, ( const ASInt32 index ), index)
+
+/**
+ Opens the user interface that allows the user to edit the specified
+ signature appearance entry of the DSAP file.
+ @param previewData Data with which to create a signature
+ preview in the edit dialog.
+ @param index The position of the entry to edit. The first
+ entry is at index <code>0</code>. A negative value gets the default entry.
+ An index larger than the current number of entries creates
+ a new entry.
+ @return <code>true</code> if successful (the changes to the entry were made and
+ saved), <code>false</code> otherwise.
+ @see DSAPFileCanDeleteNthEntry
+ @see DSAPFileCopyNthEntry
+*/
+PIPROC(ASBool, DSAPFileEditNthEntry,
+ ( const APPreview previewData, const ASInt32 index ), previewData, index )
+
+/**
+ 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.
+
+ <p>When you copy a default appearance entry, the copy is not
+ considered a default appearance entry. </p>
+ @param index The position of the entry to copy. The first
+ entry is at index <code>0</code>. A negative value gets the default entry.
+ @return <code>true</code> if the copy was successful and the appearance file
+ was successfully edited and saved, <code>false</code> otherwise.
+ @see DSAPFileCanDeleteNthEntry
+ @see DSAPFileEditNthEntry
+*/
+PIPROC(ASBool, DSAPFileCopyNthEntry, ( const ASInt32 index ), index)
+
+/************************************************************************************
+ * PubSec Acrobat Address Book (AAB) API
+ ***********************************************************************************/
+
+/**
+ 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.
+ @param x509 The certificate identifier, as defined in
+ X.509 (RFC 3280).
+ @param size The size of the certificate pointed to by
+ <code>x509</code>.
+ @return <code>true</code> if the certificate is found, <code>false</code> otherwise.
+ @see AABGetCertTrust
+*/
+PIPROC(ASBool, AABIsCertPresent, ( const ASUns8* x509, ASInt32 size ), x509, size )
+
+
+/**
+ Finds the specified certificate in the Acrobat Address Book
+ and returns the trust level.
+ @param inX509Cert The certificate identifier, as defined
+ in X.509 (RFC 3280). This is a generic 8-bit pointer to
+ the certificate data.
+ @param inX509CertSize The size in bytes of the X.509 certificate
+ pointed to by <code>inX509Cert</code>.
+ @param inCertChain An ASCab containing the certificate
+ chain for the certificate, with the trust level for each
+ certificate. It starts with the <code>inX509Cert</code> parameter's issuer at index
+ <code>0</code> and continues in the issuing order. Can be <code>NULL</code> if the
+ chain is not available.
+ @param inHelperCerts An ASCab containing an unordered
+ sequence of certificates that can be used to build the certificate
+ chain. If <code>inCertChain</code> is <code>NULL</code> and <code>inX509Cert</code> 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:
+ <p><code>{ ("0", cert1), ("1", cert2), ... }</code></p>
+
+ @return The trust value for the specified certificate, if found.
+ If no certificate is found, it returns kPSSigTrustUntrusted.
+ To distinguish a certificate that is not found from one
+ whose trust level is reported as untrusted, use AABIsCertPresent().
+
+ @see AABGetTrustedCerts
+ @see AABIsCertPresent
+*/
+PIPROC(PSSigTrust, AABGetCertTrust,
+ ( const ASUns8* inX509Cert, ASInt32 inX509CertSize, ASCab inCertChain, ASCab inHelperCerts ),
+ inX509Cert, inX509CertSize, inCertChain, inHelperCerts )
+
+/**
+ Performs a lookup in the Acrobat Address Book by certificate
+ subject name. It returns all certificates that match the name
+ along with trust information associated with them.
+
+ <p>The returned ASCab contains: </p>
+ <ul>
+ <li>An entry for each certificate, with a 0-based index followed by the X509 certificate as ASN1-encoded binary data. </li>
+ <li>An entry with a key <code>Tn</code> containing the associated trust value of each certificate, where <code>n</code> corresponds to the certificate's index key. </li>
+ </ul>
+
+ <p>If a trust key is missing, the value should be assumed to
+ be untrusted. For example: </p>
+
+ <p><code>{ ("0", cert1), ("1", cert2), ("T1", kPSSigTrustAuthenticDocuments) } </code></p>
+
+ <p>In this case, <code>cert1</code> is untrusted, <code>cert2</code> is trusted for authentic documents. </p>
+
+ @param inCertNameData The subject name of the certificates
+ to find. Specify a BER-encoded value of <code>ASN.1 type Name</code>
+ defined in X.509 (RFC 3280).
+ @param inCertNameSize The size of the certificate subject
+ name data.
+ @param outResults (Filled by the method) An ASCab containing
+ any certificates, and their trust information, found by the lookup.
+ @return <code>true</code> if successful, <code>false</code> otherwise.
+ @see AABGetCertTrust
+ @see AABGetTrustedCerts
+*/
+PIPROC(void, AABFindCertsByName,
+ ( const ASUns8* inCertNameData, ASInt32 inCertNameSize, ASCab outResults ),
+ inCertNameData, inCertNameSize, outResults )
+
+/**
+ Finds the certificates with a specified level of trust in
+ the Acrobat Address Book.
+ @param inTrust The level of trust for which to find certificates.
+ It is a logical <code>OR</code> of PSSigTrust bit flags.
+ @param 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:
+ <p><code>{ ("0", cert1), ("1", cert2), ... }</code></p>
+
+ @return <code>true</code> if successful, <code>false</code> otherwise.
+ @see AABGetCertTrust
+*/
+PIPROC(void, AABGetTrustedCerts,
+ ( PSSigTrust inTrust, ASCab outResults ), inTrust, outResults )
+
+/**
+ Finds the certificate chain for the specified certificate
+ in the Acrobat Address Book.
+
+ <p>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: </p>
+
+ <p><code>{ ("0", cert1), ("1", cert2), ... } </code></p>
+
+ @param inX509Cert The certificate identifier, as defined
+ in X.509 (RFC 3280). This is a generic 8-bit pointer to
+ the certificate data.
+ @param inX509CertSize The size in bytes of the X.509 certificate
+ pointed to by <code>inX509Cert</code>.
+ @param inTrustedCerts An ASCab containing the user's trusted
+ certificates.
+ @param inUntrustedCerts An ASCab containing additional
+ certificates needed to build the certificate chain.
+ @param outChain (Filled by the method) An ASCab containing
+ the certificate chain. The specified certificate itself
+ is at index <code>0</code>, followed by the chain certificates in issuing
+ order.
+ @return <code>true</code> if successful, <code>false</code> otherwise.
+ @see AABGetTrustedCerts
+*/
+PIPROC(ASBool, AABGetCertChain,
+ ( const ASUns8* inX509Cert, ASInt32 inX509CertSize, ASCab inTrustedCerts, ASCab inUntrustedCerts, ASCab outChain ),
+ inX509Cert, inX509CertSize, inTrustedCerts, inUntrustedCerts, outChain )
+
+/************************************************************************************
+ * Import/Export Facilities
+ * Use to import/export certificates, requests for certificates, etc to FDF
+ * files or other file types. Includes support to export to a file or
+ * to email. Uses wizard-like user interface
+ ***********************************************************************************/
+
+/**
+ Exports certificates, requests for certificates, and so
+ on, to FDF files or other file types, using a user interface wizard.
+ It includes support to export to a file or to email.
+
+ <p>The specified type of data is exported to a file and optionally
+ emailed to a destination that is chosen using the wizard: </p>
+
+ <ul>
+ <li>If the data is saved to a file and is the user's own contact information, it can be a PKCS#7 file (.p7c). </li>
+ <li>If the data contains just one certificate and is saved to a file, it can be a raw certificate file (.cer). </li>
+ <li>Otherwise, it is always an FDF file. </li>
+ </ul>
+
+ <p>It does not raise or throw exceptions. It displays an alert if it is unsuccessful. </p>
+
+ @param params A structure containing the export parameters.
+ @return <code>true</code> if successful, <code>false</code> otherwise.
+ @see PSImportDataExchange
+*/
+PIPROC(ASBool, PSExportDataExchange,
+ ( PSExportDataExchangeParams params ), params)
+
+/**
+ Imports FDF data from a file, using a user interface wizard.
+ The parameters structure specifies the type and location
+ of the data. This call is used, for example, by the Directory
+ configuration dialog box to import directory settings from an
+ FDF file.
+
+ <p>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, and then calls the handler's PSImportDataProc() using
+ the handler and engine specified in the parameters structure. </p>
+
+ <p>The operation fails if the data is not of the specified
+ type. It does not raise or throw exceptions. It displays an alert if unsuccessful. </p>
+
+ @param params A structure containing the import parameters.
+ @return <code>true</code> if successful, <code>false</code> otherwise.
+ @see PSExportDataExchange
+*/
+PIPROC(ASBool, PSImportDataExchange,
+ ( PSImportDataExchangeParams params ), params)
+
+/**
+ Tests whether any certificate in a chain has been issued
+ under the Adobe Test Certificate Policy.
+
+ <p>If this function returns <code>true</code>, PubSec handlers are recommended
+ to provide feedback to the user regarding the test nature
+ of the certificate, which may render it untrustworthy. </p>
+ @param 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:
+
+ <p><code>{ ("0", cert1), ("1", cert2), ... }</code></p>
+
+ <p><code>certn</code> is an X509 certificate as ASN1-encoded binary data.</p>
+
+ @return <code>true</code> if any certificate in the chain was issued under the Adobe Test Certificate Policy.
+*/
+PIPROC(ASBool, PSCertIssuedUnderTestCP,
+ ( ASCab inCertChain ), inCertChain)
+
+/**
+ As functions PSDataBufferEnum() or PSDataBufferDigest() are stateful (for example, the <code>dataBuffer</code>
+ object keeps track of the bytes that have been returned), call this function whenever
+ the state maintained within the <code>dataBuffer</code> need to be re-initialized.
+ @param dataBuffer The buffer containing the stateful information.
+ @see PSDataBufferEnum
+ @see PSDataBufferDigest
+*/
+PIPROC(void, PSDataBufferReset, ( PSDataBuffer dataBuffer ), dataBuffer )
+
+
+/**
+ Tests whether any certificate in a chain has been issued
+ under the Adobe Root Certificate Policy.
+
+ @param 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:
+ <p><code>{ ("0", cert1), ("1", cert2), ... }</code></p>
+
+ @return <code>true</code> if any certificate in the chain was issued
+ under the Adobe Root Certificate Policy.
+*/
+PIPROC(ASBool, AABIsCertUnderAdobeRoot,
+ ( ASCab inCertChain ), inCertChain)
+
+/**
+ Attach the a document to an eEnvelope using the specified
+ certificate data.
+
+ <p> This function calls <code>addRecipientListCryptFilter</code> and
+ <code>importDataObject</code>.</p>
+
+ @param inDIPath Path to the document to add and secure as an attachment
+ to <code>pdDoc</code>.
+ @param szAttName The attachment's name.
+ @param inCertChain The certificate identifier. This is a generic 8-bit
+ pointer to the hex-encoded raw value of the certificate data.
+ @param inCertSize The size in bytes of the certificate pointed to by
+ <code>inCertChain</code>.
+ @param pdDoc The document provided by the caller to which <code>szAttName</code>
+ will be attached and secured.
+
+ @return <code>true</code> if the the <code>pddAttachment</code> is
+ secured and attached properly to the <code>pdDoc</code>.
+
+ @see addRecipientListCryptFilter
+ @see importDataObject
+*/
+PIPROC(ASBool, PSAddSecureAttachmentToDoc,
+ (ASText inDIPath, ASText inAttName,const ASUns8* inCertChain, ASInt32 inCertSize, PDDoc pdDoc),
+ inDIPath, inAttName,inCertChain, inCertSize, pdDoc)
+
+
+
+
+
+
+
|