Home

3-Heights™ PDF Security API, User Manual

1. Object library modules Pee eel ermel32 lib user32 lib gdi32 lib winspool li IV Generate debug info Ignore all default libraries IV Link incrementally TF Generate mapfile I Enable profiling Project Options PdfSecureAPl lib kemel32 lib user32 lib gdi32 lib winspool lib comdlg32 lib advapi32 lib shell32 lib ole32 lib oleaut32 fib uuid lib kemel32 lib user32 lib Yi 3 Add the path where the dynamic link library pdfsecureapi dil resides to the Executable files directories E g as shown in the screenshot below In most cases it works to simply add it to the environment variable PATH Te ta Editor Tabs Debug Compatibility Build Directories E Platform Show directories for win32 ed Executable files z Directories C Program Files Microsoft Visual Studio Common MSDev98 Bin C Program Files Microsoft Visual Studio VC98 BIN C Program Files Microsoft Visual Studio CommonTOOLS C Program Files Microsoft Visual Studio Common TOOLS wWINNT D projects PDF testeny input bin CAWINNT system32 C WINNT There is a C sample available within the ZIP archive of the evaluation and release version that shows how to decrypt and encrypt a PDF document as well as how to add a digital signature The C sample below is much simpler and does not add a digital signature Before the C interface can be used to create objects it must be initialized once This is done using PdfSecurelnitialize
2. Sign an empty signature field An empty signature field can be added using AddSignatureField This method must be called prior to SaveAs or SavelnMemory Parameters pSignature The digital signature that is to be added Return value True Successfully placed the signature into the signature field False Otherwise Terminate Method Void Terminate Terminate all open sessions and finalize and unload all PKCS 11 drivers Some drivers require Terminate to be called Otherwise your application might crash and or your HSM USB token or smart card might not be unlocked When using the C C API Terminate may not be called from the context of the destructor of a global or static object an atexit handler nor the DllIMain entry point Make sure to end all open sessions and dispose of all PdfSecure objects before calling Terminate After calling Terminate the process may not call any other methods of this class TestSession Method Boolean TestSession Test if the current session is still alive Return value True Subsequent calls to SaveAs and SavelnMemory are likely to succeed False Subsequent calls to SaveAs and SavelnMemory are unlikely to succeed Error codes are the same as in SaveAs where applicable PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 61 71 ValidateSignature Method Boolean ValidateSignature Pd Signature
3. PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 24 71 To encrypt a document similar as above but in addition also have the application prompt the user for a pass word to open and read the document you can add a user password as additional parameter in the SaveAs function SaveAs C temp output pdf userpwd ownerpwd ePermPrint To not encrypt a document at all set empty passwords and ePermNoEncryption 1 for permission flags SaveAs C temp output pdf ePermNoEncryption How to Read an Encrypted PDF Document A PDF document which is not encrypted or protected with an owner password only can be read and decrypted by the 3 Heights PDF Security API s Open function without providing a password In Visual Basic that looks like this Open C temp input pdf A PDF document which is protected by a user password can only be opened if either the user or the owner password is provided as parameter in the Open function Technically it does not matter later on which of the two passwords was provided because both will grant full access to the document However it is up to the application programmer to distinguish between input documents that are password protected or not How secure is PDF Encryption Any PDF application that is to process or display a PDF document must be able to read and decrypt the contents of the pages in order to be able to display them It technically
4. Get the encryption filter of the signature such as Adobe PPKLite FontName1 Property String FontNamei Accessors Get Set Default 4 This property represents the path to the font name used in upper text i e the text that is set by the property Text1 Setting this property is optional on Windows and required on Non Windows platforms Fontname2 Property String Fontname2 Accessors Get Set Default This property represents the path to the font name used in lower text i e the text that is set by the property Text2 Setting this property is optional on Windows and required on Non Windows platforms PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 64 71 FontSize1 Property Single FontSizel Accessors Get Set Default 16 Define the font size of the Text1 FontSize2 Property Single FontSizel Accessors Get Set Default 8 Define the font size of the Text2 HasSignature Property Boolean HasSignature Accessors Get Get whether the signature has an actual digital signature object or not ImageFileName Property String ImageFileName Accessors Get Set Default Define the path to an image file that is to be added to the signature The image is centered and scaled down proportionally to fit into the given rectangle If the path is NULL or the image does not exist the appearance s
5. User Manual 3 Heights PDF Security API Version 4 5 TOOLS COM remiu m PDF Technolog Contents 1 INTEOCUCTION s ss s ocios a e A A e 1 Ll ADOSCrPUON A A a A 4 olan ane AA Alon Wa LARA AA A aes 1 12 FUNCION S as a aoaaa A A A a A as aaa 2 13 WMtEACES 44 4 56005 rra e tad sea 3 1 4 Operating Systems r po adobo Gos de deg a a boa 3 1 5 Howto Best Read this Manual 1 0 ec eee 3 1 6 Digital Signatures asin ani a A ate Had a A GENO AAA 3 Whatis an Electronic Signature oia sce 4 sob ia a A A SOR ea 4 How to Create Electronic Signatures ooo 6 2 Installation and Deployment o oooooocoocnocnocnnoooooooooooo romo oo oooo 7 2 WINDOWS aves Gis ee Ra A E date a A BE ea a e ar G D dat 7 A A RNA RN 7 23 MMterfac S cun a a A A Ls See We ede ee 9 2 4 Interface Specific Installation Steps o o oooooooooor eee eee 11 2 5 Uninstall Install a New Version ee ee eee ee ene 12 2 6 Note about the Evaluation Version 1 0 ee eee 12 3 License Management oooooooconononroncrnononononannononans 13 3 1 Graphical License Manager Tool 1 1 ee 13 3 2 Command Line License Manager Tool 1 eee 14 33 License Key Storage ui O to Nd ara E ee NS 14 4 Programming Interfaces 2 cee eee eee eee ee ee eee eee eee eee eee eee 15 Ao Visual BasiCiO eri AAA aaa Aa AA os Wha AAA aes 15 A2 CCEE ie Sick NANA 17 43 ANET ara ews ae Ae ea AS AD Rad
6. Value The value as string Retrieve or add a key value pair to the documents info object Values of predefined keys are also stored in the XMP metadata package Popular entries defined by the PDF Specification and used by most PDF viewers are Title Author Subject Creator sometimes referred to as Application and Producer sometimes referred to as PDF Creator Examples in Visual Basic 6 Get document title t InfoEntry Title Set document title InfoEntry Title my title Set the creation date to 13 55 33 April 5 2010 UTC 2 InfoEntry CreationDate D 20100405135533 02 00 NoCache Property Boolean NoCache Accessors Get Set Default False Get or set whether to disable the cache for CRL and OCSP responses Using the cache is safe since the responses are cached as long as they are valid only The option affects both signature creation and validation See section on caching for more information on the caches Open Method Boolean Open String FileName String Password Open a PDF file or raster image file i e make the objects contained in the document accessible If a document is already open it is closed first Parameters FileName The file name and optionally the file path drive or server string according to the operating systems file name specification rules Password optional The user or the owner password of the encrypte
7. Issued to When using a Windows OS the certificate must be available in the Windows certificate store See also chapter Digital Signature This property can be used to select the signer certificate for signing see description of Cryptographic Provider in use PageNo Property Long PageNo Accessors Get Set Default 1 last page Define the page number where the signature is to be added to the document If an invalid page number is set it is added to the last page Provider Property String Provider Accessors Get Set Default Windows only Microsoft Base Cryptographic Provider v1 0 This property specifies the cryptographic provider used to create and verify signatures For more information on the different providers available see the description in the respective subsection of the section Cryptographic Provider When using the Microsoft CryptoAPI Provider the value of this property with the following syntax ProviderType Provider PIN Examples 123456 being the pin code Provider Microsoft Base Cryptographic Provider v1 0 123456 Provider 123456 PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 66 71 When using the PKCS 11 Provider the value of this property is to be set to a string with the following syntax PathToD11 Slotld Pin Examples Provider WINDOWS system32 siecap11 d11 4 123456 When us
8. File must contain the certificate itself all certifi cates of the trust chain and the private key Ee ait String optional Password to decrypt the private key of the SLL client certificate SSLServerCertificate File recommended Certificate of the server or its issuer CA certifi cate in DER Format der cer Note If this property is not set the server cer tificate is not verified at all RequestID String recommended Any string that can be used to track the re quest Example An UUID like AE57F021 COEB 4AE0 8E5E 67FB93E5BC7F Signature Configuration The signature can be customized using standard properties of the 3 Heights PDF Security API Description Required Value Setting Common Name required The name ofthe signer should be set Property Name Time stamp optional urn iett rfc 3161 Property TimeStampURL Revocation Info optional true to embed OCSP responses or Property EmbedRevocationinfo CRL METE MN TIE TEA optional See separate chapter on creating a vi sual appearance Proxy Configuration Ifa proxy is used for the connection to the service see chapter Howto Use a Proxy for more information 2This parameter is not used for certificate selection but for the signature appearance and signature description in the PDF only O PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 33 71 5 5 5 SwissSign SuisselD Signing Service In order to use the SuisselD Sig
9. PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 31 71 lt password gt password of the token Examples Provider http server mydomain com 8080 0001 pass01 A more detailed description can be found in the user manual of the 3 Heights Signature Creation and Validation Service Selecting a Certificate for Signing Selection of the signing certificate works the same as if the token was used directly Selecting a Certificate for Signing PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 32 71 5 5 4 SwissSign Personal Signing Service Provider Property Provider The provider configuration string contains the URL to the service endpoint Provider Configuration The provider can be configured using provider session properties There are two types of properties String Properties String properties are set using method SetSessionPropertyString File Properties File properties are set using method SetSessionPropertyString with a file name parameter Alterna tively the file can be passed in memory as byte array using the method SetSessionPropertyBytes Name Type Required Value Identity String required The identity of your signing certificate Example My Company Signing Cert 1 DSSProfile String required http dss swisssign net dss profile pades 1 0 SSLClientCertificate File required SSL client certificate in PKCS 12 Format p12 pfx
10. The chapter Guidelines for Mass Signing contains important information to optimize performance when signing multiple documents Interoperability Support The following cryptographic token interface PKCS 11 products have been successfully tested SafeNet Protect Server SafeNet Luna SafeNetAuthentication Client IBM OpenCrypTokl a CryptoVision Siemens CardOS Selecting a Certificate for Signing The 3 Heights PDF Security API offers different ways to select a certificate The product tries the first of the following selection strategies for which the required values have been specified by the user 1 Certificate fingerprint Property SignerFingerprint SHA1 fingerprint of the certificate The fingerprint is 20 bytes long and can be specified in hexadecimal string representation e g b5 e4 5c 98 5a 7e 05 ff f4 c6 a3 45 13 48 Ob c6 9d e4 5d f5 In Windows certificate store this is called Thumbprint if Thumbprint algorithm is shat 2 Certificate Issuer and SerialNumber Properties Issuer and SerialNumber PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 27 71 Certificate Issuer e g QV Schweiz CA in Windows certificate store this is called Issued By Serial number of the certificate hexadecimal string representation e g 4c 05 58 fb This is a unique number assigned to the certificate by its issuer In Windows certificate store thi
11. 63 71 other than the root certificate is embedded as well This implies that both OCSP responses and CRLs can be present in the same message The downsides of embedding revocation information are the increase of the file size normally by around 20k and that it requires a connection to a validation service which delays the process of signing normally by around 2 seconds For mass signing it is suggested to use the caching mechanism see chapter Caching of CRLs OSCP and TSP Responses Embedding revocation information requires an online connection to the CA that issues them The firewall must be configured accordingly In case a web proxy is used it must be ensured the following MIME types are sup ported when using OCSP not required for CRL application ocsp request application ocsp response If EmbedRevocationInfo is set to true but the embedding failed e g because the OCSP server is not reachable the return value of SaveAs is true and the ErrorCode after SaveAs is SIG_CREA_E_OCSP FillColor Property Long FillColor Accessors Get Set Default 16761024 red 192 green 192 blue 255 This property represents the color of the signature s background as an RGB value In order to not set a color i e keep the rectangle transparent set the FillColor to 1 This is particularly useful in combination with adding an image to the signature Filter Property String Filter Accessors Get
12. COM Projects Browse Recent Look in bin c Ed a PdfsecureAP1 dil S edfSecureNeT cll File name ras ecureNET dll ibpdfNET dll Files of type Component Files dll tlb olb ocx exe manifest import namespaces Note This step is optional but useful 4 Write Code Steps 3 and 4 are shown separately for C and Visual Basic PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 20 71 Visual Basic 3 Double click My Project to view its properties On the left hand side select the menu References The NET assemblies you added before should show up in the upper window In the lower window import the namespaces Pdftools Pdf and Pdftools PdfSecure You should now have settings similar as in the screenshot below Application Configuration N A hd Platform N A Le Compile Unused References Reference Paths Debug References Reference Name__ Type version Copy Local Path SooS References libpdFNET NET 1 0 0 0 True C Program Filesipdf tools binilibpdFNET dl PdfSecureNET NET 1 0 0 0 True C Program Files pdf tools bin PdfSecureNET dll Resources System NET 2 0 0 0 False C WINNT Microsoft NET Framework v2 0 5072715ystem dll System Drawing NET 2 0 0 0 False C WINNT Microsoft NET Framework v2 0 50727 5ystem Drawing dll Settings System Windows Forms NET 2 0 0 0 False CiWINNT1Micros
13. Friendly Name Satus ones Personal store contains 1 certificate PDF Security API Version 4 5 August 26 2015 29 71 7 Double click the certificate to open The certificate name corresponds to the value Issued to Certificate 3 Certificate Information This certificate is intended to Ensures the identity of a remote computer Proves your identity to a remote computer Ensures software came from software publisher Protects software from alteration after publication Protects e mail messages Allows data to be signed with the current time y Issued to Philip Rengali Issued by Philip Rengali Yalid from 11 12 2006 to 11 12 2011 P You have a private key that corresponds to this certificate 8 In the tab Detail of the certificate there is a field named Key Usage This field must contain the value Digital Signature Additional values are optional see also screenshot You must have the private key that corresponds to this certificate Certificate Montag 11 Dezember 2006 1 Sonntag 11 Dezember 2011 CH philip renggli pdf tools c RSA 1024 Bits a Enciph shal 358D ABBE E427 1F3C 689C A Digital Signature Data Encipherment 90 PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 30 71 Qualified Certificates A qualified certificate can be obtained from a certificate authority CA Besid
14. It can for instance set an owner password so that only authorized users can edit and change the document A user password ensures that only authorized users have access to the document s content The tool s signature module allows the user to apply read and verify both classic digital signatures and MDP modification detection and prevention signatures The visibility and visual appearance of digital signatures can be adapted to suit requirements The tool also supports customized signature handlers and types Features Apply simple advanced and qualified electronic signatures Apply PAdES LTV Long Term Validation signatures Cache OCSP CRL and TSP responses for mass signing Apply modification detection amp prevention MDP signatures Apply document time stamp signatures Encrypt and decrypt PDF documents Set user authorizations including Print document Modify document content Extract or copy content Add comments Fill in form fields Content extraction for accessibility Assemble documents Print in high resolution Set crypt and stream filters Set encryption strength Set owner and user password Stamping PDF A compliant stamps Modify existing stamps Stamping of signed documents preserves existing signatures Formats Input Formats PDF 1 x e g PDF 1 4 PDF 1 5 PDF A 1 PDF A 2 PDF A 3 Target Formats PDF 1 x e g PDF 1 4 PDF 1 5 PDF A 1 PDF A 2 PDF A 3 Complian
15. Read the chapter User s Guide for general information about the API Read Programmer s Refer ence for specific information about the functions of the API RUNS 1 6 Digital Signatures Overview Digital signature is a large and slightly complex topic This manual gives an introduction to digital signatures and describes how the 3 Heights PDF Security API is used to apply them It does however not describe all the technical details Terminology Digital Signature is a cryptographic technique of calculating a number a digital signature for a message Creat ing a digital signature requires a private key from a certificate Validating a digital signature and its authorship requires a public key Digital Signature is a technical term Electronic Signature is a set of electronic data that is merged or linked to other electronic data in order to authen ticate it Electronic Signatures can be created by means of a digital signature or other techniques Electronic Signature is a legal term Table Abbreviations CA Certification Authority CMS Cryptographic Message Syntax CRL Certificate Revocation List CSP Cryptographic Service Provider HSM Hardware Security Module PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 5 71 OcsP Online Certificate Status Protocol PKCS Public Key Cryptography Standards QES Qualified Electronic Signature TSA Time stamp Authority TSP Time stamp Protocol Why
16. String StmF Create an output PDF document apply the security settings and save the content from the input file to the output file The last three parameters KeyLength StrF StmF are only relevant in specific cryptographic situations In all other cases it is easiest to use the default values 128 V2 V2 Parameters FileName The file name and optionally the file path drive or server string according to the operating systems file name specification rules UserPwd optional Set the user password of the PDF document If this parameter is omitted the default password is used Use 0 to set no password OwnerPwd optional Set the owner password of the PDF document If this parameter is omitted the default password is used Use 0 to set no password PermissionFlags optional The permission flags By default no encryption is used 1 The permissions that can be granted are listed at the enumeration TPDFPermission To not encrypt the output document set PermissionFlags to ePermNoEncryption 1 user and owner password to 0 In order to allow high quality printing flags ePermPrint and ePermDigitalPrint need to be set PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 58 71 KeyLength optional Default 128 The key length is a determining factor of the strength of the encrypting algorithm and the amount of time to break the cryptographic system For RC4 t
17. What operations in a PDF document are granted is controlled via its permission flags In order to set permission flags the PDF document must be encrypted and have an owner password The owner password is required to initially set or later change the permission flags These access permission flags are Modifying the content of the document Copying or extracting text and graphics from the document Adding or modifying text annotations and interactive form fields Printing the document low or high quality Filling in form and digitally signing the document Assembling the document inserting rotating deleting pages etc How to Encrypt a PDF Document If either of the passwords or permission flags is set the document is encrypted If only a user password is set but no owner password and no permission flags the owner password is equal to the user password and all permissions are granted In the 3 Heights PDF Security API the passwords and permission flags are provided as parameters of the SaveAs function Note that the PDF Specification accepts an empty string as password PDF applications by default try to open documents with the empty string password To encrypt a document and protect it against any manipulations other than printing the document must have an owner password and the print permission flag set In Visual Basic such as SaveAs call would look like this SaveAs C temp output pdf ownerpwd ePermPrint
18. CES ks 54 GetREVISOM 2 see a ene RR RA RR ER De ee Pee AAA AA eRe we 54 GetSignature os es bk ee a eae Se Eee ae a eee seed Va Se Bale eS Eh Sk ea eed 54 INTOENt Y lo es i s a aig APR ee ity Goce oy Git a re Sioa de Whe Ge rds ae le aE a Ge pe nest toe a ed 55 Nocac os 2 4 dut Gast dh Eve toh eee de bh hehe oe See bad eh tie bah dened 55 ODER she miarat oe ie a a w Gress AO RAR 55 Open Me deca a BR OE RES a AOR GG Ae ale Ae Be A ne ee ice ae te 55 REVISIONCOUNE ose vas bl ea LER hee ee Ee ewe EER Rea EA Ge a eB ae Se RA ONG aes 56 SAVEAS 25 ja se eR AAA REE TRE LR eR EHR EOE RG ae DE eee ee Rada a ba We a ees 56 SavelnMemoryc amp naira a a a Re Sk ee a wate ew a he ha a Bald ae 58 SetSessionPrOPertY siea eck cel oy ana adele A geod om WIGS Me Wedge i ge US a ae bo gabe cee 58 SIZMAtUreGOUNES tata ad ra alee Spal ae Roe PE Sea RRS Hak a ee RAE ae ae So 58 SignPreparedSignature 5 24 5 eho Re eee ew eR Se a eA aS OHNE a Se a ae WS Ved 59 SignSignatureField n sonos eand aa RG BERR EG Ee ER RA Sa ee a eae 59 Terminate saas oir da e Abe dai Beaks AAS My Reames Bae Re ds An Se Bea Deeg ti dae eesti He Gee aie eos 59 TestS SSION ssa aci ra e da de RUG MLAs eda Boa gee ay a ap a Ge Wee eae ane Bea koe wees 59 ValidateSisnature acca aww Re Se bce BE a Ee ee BALE OR A SH ee Bae SRA ad 60 6 2 PdfSignature INt rface s reai dace aha aa dod Wala Ran ai E ae a ld eMac ata 60 Contactinfo lr A Bia Baal eee Ad e a 60 Date eisers a RAR A RA R
19. For example http services sealsignportal com 18080 sealsign ws BrokerClient Provider Configuration The provider can be configured using provider session properties that can be set using the method Set SessionPropertyString Name Type Required Value Identity String required The account ID is the unique name of the ac count specified on the server Example Rigora Profile String required The profile identifies the signature specifica tions by a unique name Example Default secret String required The secret is the password which secures the access to the account Example NeE EKEd33FeCk70 clientid String optional A client ID can be used to help separating ac cess and creating better statistics If specified in the account configuration it is necessary to provide this value Example 3949 4929 3179 2818 String required The PIN code is required to activate the sign ing key Example 123456 WESEN a String optional The message digest algorithm to use Note that the supported algorithms depend on the provider Default SHA 256 Alternatives SHA 1 SHA 384 SHA 512 RIPEMD 160 RIPEMD 256 Signature Configuration The signature can be customized using standard properties Description Required Setting Common Name required The name ofthe signer should be sett Property Name Time stamp Not available Revocation Info optional true to embed OCSP responses or Property EmbedRevocationinfo CRL METE WAN E
20. Requirements for qualified certificates and signatures vary depending on the country where they are issued and used A Qualified Electronic Signature is similar to an advanced electronic signature but has higher requirements The main differences are Itis based on a qualified certificate which is provided as a hardware token USB stick smart card For every signature it is required to enter the PIN code manually This means that only one signature can be applied at a time Certificate revocation information OCSP CRL can be acquired from an online service The response valid revoked etc must be embedded in the signature A time stamp TSP that is acquired from a trusted time server TSA may be required This brings the following advantages over an advanced electronic signature The signature ensures the certificate was valid at the time when the document was signed due to the embedding of the OCSP CRL response The signature ensures the integrity of the time of signing due to the embedding of the time stamp Legal processes that require a QES are supported Note that a Time stamp can be added to any type of signature OCSP CRL responses are also available for some advanced certificates PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 7 71 1 6 2 How to Create Electronic Signatures Preparation Steps 1 Identify whether an advanced or a qualified signature is requ
21. an invisible signature set the rectangle to 0 0 0 0 Hint about using this property in programming language that do not support the type Variant In order to find out what type you should use create a PdfSignature object and look at the default value of the property in the debugger PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 67 71 Revision Property Integer Revision Accessors Get Return the revision number of the PDF document associated with this signature The associated PDF document can be retrieved using the method GetRevision SerialNumber Property String SerialNumber Accessors Get Set The serial number with the issuer can be used to select a certificate for signing This property is a hex string as displayed by the Serial number field in the Microsoft Management Console MMC e g 49 cf 7d d1 6c a9 This property can be used to select the signer certificate for signing see description of Cryptographic Provider in use SignerFingerprint Property Variant SignerFingerprint Accessors Get Set The sha1 fingerprint of the signer certificate This property can be used to select the signer certificate for signing see description of Cryptographic Provider in use After validating a signature this property contains the validated signature s fingerprint SignerFingerprintStr Property String SignerFingerprin
22. and log the error code and error message PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 59 71 Printing Allowed None Low Resolution ePermPrint High Resolution ePermPrint ePermDigitalPrint Changes Allowed None Inserting deleting and rotating pages ePermModify Filling in form fields and signing existing signature fields ePermAnnotate Commenting filling in form fields and signing existing signature fields ePermAnnotate ePermFillForms Any except extracting pages ePermModify ePermAnnotate ePermFillForms Enable copying of text images and other content ePermCopy ePermSupportDisabilities Enable text access for screen reader devices for the visually impaired ePermSupportDisabilities These flags can be combined For example to grant permission which are equal to Acrobat s 7 Printing Allowed High Resolution and Enable copying of text images and other content set the flags ePermPrint ePermCopy ePermSupportDisabilities ePermDigitalPrint SavelnMemory Method Boolean SavelnMemory String UserPw String OwnerPw TPDFPermission PermissionFlags Long KeyLength String StrF String StmF Save the output PDF in memory After the Close call it can be accessed using the method GetPDF All parameters are identical to the SaveAs method See also chapter How to use the in Memory Functions Return value True The d
23. as an RGB value In order to not set a color i e keep it transparent set the StrokeColor to 1 SubFilter Property String SubFilter Accessors Get Get the name of the sub filter such as adbe pkcs7 detached Text1 Property String Texti Accessors Get Set Default un This is the upper text that is added to the signature If this property is set to blank the signature name is added to the upper text line of the visual signature In order to position text use the following syntax lt tab gt lt x gt lt y gt lt delimiter gt lt text gt tab tabulator x y integers delimiter Single character such as space text Any text string not containing a lt tab gt Example for Visual Basic NET Dim sig As New PdfSecure Signature sig Texti Microsoft VisualBasic vbTab amp 5 50 Peter Pan sig Text2 Microsoft VisualBasic vbTab amp 15 25 Signed this document Text2 Property String Text2 Accessors Get Set Default Y This is the lower text that is added to the signature The text can be multi lined by using linefeed W OXA If this property is set to blank a text three line text is constructed that consists of A statement who applied to signature The reason of the signature The date See also property Text1 If you want the appearance to not contain any text set this property to a space PDF Tools AG Premium PDF Technology PDF Security API V
24. as memory block using the method AddStampsMen Astamp file can contain one or more stamps Each stamp is defined by a ps stamp tag that specifies the stamp s size position and pages to which it is applied to Each stamp contains a number of content operators that define the appearance i e the content of the stamp The content operators are applied in the order they appear within ps stamp where each content element is drawn over all previous elements i e increasing z order Tags Attributes Names Attribute Values ps pdfstamp The Root Tag for the PDF stamps The tag may contain multiple stamps xmln ps http www pdf tools com pdfstamp ps stamp Stamp A stamp contains a collection of content operators page first even The pages to which the stamp is to be applied Comma separated combinations are odd allowed first First page last Last page odd Only odd pages including first page and last page in case it is odd even Only even pages including last page in case it is even all All pages not_first First page excluded not_last Last page excluded name name Identifier of the stamp optional must be less than 127 characters must be unique see note 2 below relativepos x y Relative position x and y of the stamp with regards to the page Positive values of x and y define the distances of the stamp to the left and lower negative values to the right and upper page boundary respectively The positioning algorithm works best fo
25. at the time when the signature is applied to the document If this property is set to an empty string no entry is created DocumentHasBeenModified Property Boolean DocumentHasBeenModified Accessors Get Get whether the document has been modified true or not false since the selected signature was added Email Property String Email Accessors Get This property represents the email address of the signer The method ValidateSignature extracts the address from the signing certificate s subject and sets this property EmbedRevocationInfo Property Boolean EmbedRevocationInfo Accessors Get Set Default True Embed revocation information such as online certificate status response OCSP RFC 2560 and certificate revocation lists CRL RFC 3280 Revocation information of a certificate is either an OCSP response or a CRL which is provided by a validation service at the time of signing and acts as proof that at the time of signing the certificate is valid This is useful because even when the certificates expires or is revoked at a later time the signature in the signed document remains valid Embedding revocation information is optional but suggested when applying advanced or qualified electronic signatures If the embedding is enabled then the information of the signer certificate and the issuer certificates PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015
26. background is a filled rectangle using the colors FillColor and StrokeColor Note that for the output file to be PDF A the image s color space must match the document s output intent If you want the appearance to contain the image only and no text set the property Text2 to a space Issuer Property String Issuer Accessors Get Set Default un Set the issuer of the certificate The Issuer corresponds to the common name CN of the issuer In the Windows certificate store this corresponds to Issued by This property can be used to select the signer certificate for signing see description of Cryptographic Provider in use LineWidth Property Single LineWidth Accessors Get Set Default 2 This is the thickness of the line surrounding the visual appearance of the signature PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 65 71 Location Property String Location Accessors Get Set Default This is the physical location where the signature was added for example Zurich Switzerland If this property is set to an empty string no entry is created Name Property String Name Accessors Get Set Default ci In order to sign a PDF document a valid existing certificate name must be provided The Name corresponds to the common name CN of the subject In the Windows certificate store this corresponds to
27. can specify that it will be accessing the library concurrently from multiple threads and the library must ensure proper thread safe behavior However some PKCS 11 provider middleware implementations are not thread safe For this reason the 3 Heights PDF Security API synchronizes all access to the same provider middleware and slot id If your middleware is thread safe you can enable full parallel usage of the cryptographic device by setting the session property LOCKING_0K to the value true using the method SetSessionPropertyString Example Enable parallel access to the cryptographic device doc SetSessionPropertyString LOCKING_OK true PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 40 71 5 6 7 Miscellaneous Caching of CRLs OCSP and TSP Reponses In order to improve the speed when mass signing the 3 Heights PDF Security API provides a caching algorithm to store CRL Certificate Revocation List OCSP Online Certificate Status Protocol TSP Time stamp Protocol and data from signature services This data is usually valid over period of time that is defined by the protocol which is normally at least 24 hours Caching improves the speed because there are situations when the server does not need to be contacted for every digital signature The following caches are stored automatically by the 3 Heights PDF Security API at the indicated locations within the
28. containing various files including runtime binary executable code files required for the developer documentation and license terms 1 Download the ZIP archive of the product from your download account at http www pdf tools com 2 Unzip the file using a tool like WinZip available from WinZip Computing Inc at http www winzip com to a directory on your hard disk where your program files reside e g C Program Files PDF Tools AG 3 Check the appropriate option to preserve file paths folder names The unzip process now creates the following subdirectories bin Contains the runtime executable binary code doc Contains documentation files include Contains header files to include in your C C project samples Contains sample programs in various programming languages There is the option to download the software as MSI file which makes the installation easier 4 Optionally register your license key using the License Manager 5 Identify which interface you are using Perform the specific installation steps for that interface described in chapter Interfaces 6 If you want to sign documents proceed with setting up your cryptographic provider as described in chapter Cryptographic Provider 7 Ifyou want to stamp text proceed with setting the fonts required as described in chapter Fonts 2 2 Unix This section describes installation steps required on all Unix platforms which includes Linux Mac OS X Sun Solaris IBM AIX H
29. in the bin directory of the product kit y PDF Tools License Manager File Edit Help xX 2 Add Key Delete Refresh List License Properties 3 Heights TM Document Converter Name Value Y Y 0 10A0M TARAF HA O Key 0 J0A94 NAGE LIC Y 0 BCASN W EN RIOT LL POLE Product 3 Heights TM Image 3 Heights TM Image to PDF Converter API af Intended Use Productive TY 0 J0A94 iniiai cl a a fa Y Platform Windows 3 Heights TM Image to PDF Converter Service dd a ver pedian A jox id ura wap aan Y Maintainance Expiration 2033 12 31 List all installed license keys The license manager always shows a list of all installed license keys in the left pane of the window This includes licenses of other PDF Tools products The user can choose between Licenses available for all users Administrator rights are needed for modifications Licenses available for the current user only Add and delete license keys License keys can be added or deleted with the Add Key and Delete buttons in the toolbar The Add key button installs the license key into the currently selected list The Delete button deletes the currently selected license keys Display the properties of a license If a license is selected in the license list its properties are displayed in the right pane of the window Select between different license keys for a single product More than one license
30. pSignature Validate an existing digital signature which was previously retrieved using the method GetSignature The component supports the verification of signatures including Time stamps using cryptographic tokens and hardware security modules HSM through their PKCS 11 interface The validity checks are carried out at the time indicated either by the embedded time stamp if present or by the signing time indicated in the PDF signature field object otherwise Furthermore this method extracts the following values from the cryptographic signature and sets the respec tive properties of the Pdf Signature object Date Email Name Issuer SignerFingerprint and TimeStampFingerprint If you get the error code SIG_VAL_E_FAILURE your cryptographic provider does not offer the algorithms used for the signature For example the default provider Microsoft CryptoAPI does not support the SHA 2 hash algorithms In this case choose another provider Parameters pSignature The digital signature that is to be validated Return value True The digital signature is valid i e the document has not been modified If other problems are detected during signature validation the property ErrorCode may have one of the following values 1 SIG_VAL_W_ISSUERCERT 2 SIG_VAL_W_TSP 3 SIG_VAL_W_TSPCERT 4 SIG_VAL_W_NOTRUSTCHAIN 5 SIG_VAL_W_PADES Note that the order of the list defines the priority of the error codes from highest to lowes
31. the new glyph set has to be re embedded This setting is recommended for stamps that need not be modified later WinAnsi All glyphs required for WinAnsiEncoding are embedded Hence the text s characters must be limited to this character set If the content of the stamp is updated fonts using WinAnsi will be reused For example embedding the font Arial with Unicode and approximately ten glyphs uses 20KB while Arial with WinAnsi approximately 200 glyphs uses 53KB of font data PDF Security API Version 4 5 August 26 2015 51 71 Example Simple Stamps Apply two simple stamps First Stamp Stamp text Simple Stamp on in upper right corner of all pages Second Stamp Stamp image image jpg rotated by 90 at the corner of the top edge of the first page lt xml version 1 0 encoding utf 8 gt lt ps pdfstamp xmlns ps http www pdf tools com pdfstamp gt lt ps stamp page all name simple stamp relativepos 10 10 size 160 0 gt lt ps filltext align left middle fontencoding WinAnsi font Arial size 12 text Simple Stamp gt lt ps stamp gt lt ps stamp page first relativepos 0 10 align center gt lt ps rotate angle 90 origin 50 50 gt lt ps image rect 0 0 100 100 filename c images image jpg gt lt ps rotate gt lt ps stamp gt lt ps pd stamp gt Example Modify Simple Stamp Modify simple stamp from example above The stamp simple stamp can be mo
32. the registration of PdfSecureAPi dil Note that in Windows Vista and later the command needs to be executed from an administrator shell regsvr32 C Program Files PDF Tools AG bin PdfSecureAPI d1l If you are using a 64 bit operating system and would like to register the 32 bit version of the 3 Heights PDF Se curity API you need to use the regsvr32 from the directory SystemRoot SyswOw64 instead of SystemRoot ASystem32 If the registration process succeeds a corresponding dialog window is displayed The registration can also be done silently e g for deployment using the switch s Other Files The other DLLs do not need to be registered but for simplicity it is suggested that they reside in the same directory as the PdfSecureAPI dill Java Interface For compilation and execution When using the Java interface the Java wrapper jariSECA jar needs to be on the CLASSPATH This can be done by either adding it to the environment variable CLASSPATH or by specifying it using the switch classpath javac classpath C pdf tools jar SECA jar sample java For execution Additionally the library PdfSecureAPi dll needs to be on the Java system property java library path This can be achieved by either adding it dynamically at program startup before using the API or by specifying it using the switch Djava library path when starting the Java VM java classpath C pdf tools jar SECA jar Djava library path C pdf tool
33. the selected entry all certification Pals found Quovadis Root Certification Autt Y General Details Revocation Trust Policies Legal Notice El QU Schweiz ICA Trust Settings This certificate is trusted to Sign documents or data Certify documents Execute dynamic content that is embedded in a Certified document Execute high privilege JavaScripts that are embedded in a Certified document Add to Trusted Identities En 10 The selected certificate path is valid The path validation and revocation checks were done at 2010 03 12 16 21 08 01 00 x PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 43 71 Revocation Information An OCSP response or CRL must be available This is shown in the tab Revocation The details should mention that the certificate is considered valid The presence of revocation information must be checked for the signing certificate and all certificates of its trust chain except for the root certificate Certificate Viewer QuoYadis Root Certification Autb El QY Schweiz ICA Time stamp The signature can optionally contain a Time stamp This is shown in the tab Date Time The certificate of the Time stamp server must also be trusted i e its trust chain should be validated as described in the section Trust Chain above Signature Properties O PDF Tools AG Premium PD
34. 3 Enumerations Note Depending on the interface enumerations may have TPDF as prefix COM C or PDF as prefix NET or no prefix at all Java TPDFErrorCode All TPDFErrorCode enumerations start with PDF_ followed by a single letter which is one of S E W or I an underscore and a descriptive text The single letter gives in an indication of the type of error These are Success Error Warning Information With respect to corrupt PDF files An error indicates a corruption in the PDF the file may or may not be readable A warning indicates the file is readable but not valid A full list of all PDF Tools error codes is available in the header file pdferror h Note that only a few are relevant for the PDF Security API The most common are listed here PDF_S_SUCCESS LIC_E_NOTSET LIC_E_NOTFOUND PDF_E_FILEOPEN PDF_E_FILECREATE PDF_E_PASSWORD PDF_E_UNKSECHANDLER PDF_E_XFANEEDSRENDERING PDF_W_ENCRYPT SIG_CREA_E_SESSION SIG_CREA_E_STORE SIG_CREA_E_CERT SIG_CREA_E_INVCERT SIG_CREA_E_OCSP SIG_CREA_E_CRL SIG_CREA_E_TSP SIG_CREA_E_PRIVKEY SIG_CREA_E_SERVER SIG_CREA_E_ALGO SIG_CREA_E_FAILURE PDF_E_SIGLENGTH Validation specific error codes The operation was completed successfully Various license management related errors Failed to open the file Failed to create the file The authentication failed due to a wrong password The file uses a proprietary securit
35. 5 Uninstall Install a New Version If you used the MSI for the installation go to Start gt 3 Heights PDF Security API gt Uninstall If you used the ZIP file In order to uninstall the product undo all the steps done during installation e g un register using regsvr32 u delete all files etc Installing a new version does not require to previously uninstall the old version The files of the old version can directly be overwritten with the new version If using the COM interface the new DLL must be registered un registering the old version is not required 2 6 Note about the Evaluation Version The evaluation versions of the 3 Heights products automatically add a watermark to the output files O PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 14 71 3 License Management There are three possibilities to pass the license key to the application 1 The license key is installed using the GUI tool Graphical user interface This is the easiest way if the licenses are managed manually It is only available on Windows 2 The license key is installed using the shell tool This is the preferred solution for all non Windows systems and for automated license management 3 The license key is passed to the application at runtime via the LicenseKey property This is the preferred solution for OEM scenarios 3 1 Graphical License Manager Tool The GUI tool LicenseManager exe is located
36. AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 37 71 5 6 1 How to Sign a PDF Document As we saw in the chapter Digital Signatures the process steps to add a signature are as shown in the graphic below Ey Certificate Open gt AddSignature pSaveAs Close 3 Heights PDF Security API Signed PDF A PDF input document is opened A signature is created and added using a certificate Anew signed PDF output document is created The input document is closed PUNS 5 6 2 How to create a Preview of a signed Document The 3 Heights PDF Security API provides the possibility to create a PDF document with a visual appearance of a digital signature without actually signing the document This document can be used for a preview If the preview is accepted the document can be signed without visually change the document The process steps to prepare a document for signing and actually sign it upon approval of the user are as shown in the graphic below Certificate E al Open AddPreparedSignature SaveAs SignPreparedSignature SaveAs Close 3 Heights PDF Security API User accepts preview we PDF for preview Signed PDF 1 A PDF input document is opened 2 Adigital signature is prepared and a visual appearance is generated 3 A new preview PDF output document is created this document does not contain a digital signature how ever it contains a pl
37. Ced GUIAR mt a each Ale A als ee a a aa Ace DS A Ma A eae at a 44 59 Stamp oa aaa do da das nal cis 45 6 Reference Manual ico oir a a e See ee 51 6 1 PdtSecur sInterface vas ia RS EL BR cd da Ba Hea ee ea E ar 51 AddDOcMDP SisNature 5 2 ow ace A eel a ac ay RUE eat ae Gel wae aa ele ga ad Gun a ee 51 AddPreparedSignatute ca ga 8 29h 8 a GRAVE ROUSE ERAS e eee Dale See Phe a a 52 AddSigmatUTe e a hare a 8 te Macc aster wt ees 8 Rants E a Mees ees eae ates A as da Sis aca He Gogh Rice DOR home es 52 AddSignatureField ios a Lar A A NA SR ee ee a woe e a 52 AGStamps arias e a a Ph ace gS alee amp Boe a oa 52 PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 1 71 AddStamps Men cion ara aci a as an ne dae wave acs Abe Gus ii 52 AddTitmeStampSignature sio oe ach ee ee Re A BS hy Se E ES Gee RAMP eae 53 B SINSESSION vis a maala a aaa a Kg a doe ohare RE eae ade QS Dass wd ee a ed ala a ce 53 Close noe ee perga REREAD EER Aa Shae eee a Dede Pek ee Se Pee Oh Gee RA 53 ERFOPCOGG ists oe ee wht Bode ae a ee pte Bees wey Be PRA ant AA a ed Se oe Ge eo ae ee aad 53 Error Message ce sae ca ea a ek eR eee RRA A RARA aa A A E A 53 EMOSeSSION 2 4 4 pta Soha hdc eee we Rahs Gate Eh hae SS he SEA EE RES Behe 53 FORGEEMGIYDUOM cities a ee ede Beye OE a ay a a ae es Bee Soe eee es 54 FOrCESIBN AUS ii o E A A AA A e ina she Ge ed ae i ect OR aw ches 54 GetPDE oa Hae Ra Eve eid meee Sees SERS oe ee home eee a
38. Certificate Store Property Store The value for the certificate store depends on the OS Supported values are CA MY and ROOT For signature creation the default store MY is usually the right choice PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 28 71 Store Location Property StoreLocation Either of the following store locations Local Machine Current User default Usually personal certificates are stored in the current user location and company wide certificates are stored under local machine The current user s store is only available if the user profile has been loaded This may not be the case in certain environments such as within an IIS web application or COM applications Use the store of the Local Machine if the user profile cannot be loaded Certificates in the store Local Machine are available to all users However in order to sign a document you need access to the signing certificate s private key The private key is protected by Windows ACLs and typically readable for Administrators only Use the Microsoft Management Console mmc exe in order to grant access to the private key for other users as follows Add the Certificates Snap in for the certificates on Local Machine Right click on the signing certificate click on All Tasks and then Manage Private Keys where you can set the permissions Selecting a Certificate for Signing First the c
39. Contact PDF Tools AG Kasernenstrasse 1 8184 Bachenb lach Switzerland http www pdf tools com PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 73 71
40. Digitally Signing The idea of applying a digital signature in PDF is very similar to a handwritten signature A person reads a document and signs it with their name In addition to the name the signature can contain further optional information such as the date and location A valid electronic signature is a section of data that can be used to Ensure the integrity of the document Authenticate the signer of the document Prove existence of file prior to date time stamp Digitally signing a document requires a certificate and its private key How to access and use a certificate is described in the chapter Cryptographic Provider In a PDF document a digital signature consists of two parts A PDF related part This part consists of the PDF objects required to embed the signature into the PDF document This part depends on the signature type Document Signature MDP Signature see table below Information such as name of the signer reason date location is stored here The signature may optionally have a visual appearance on a page of the PDF document which can contain text graphics and images This part of the signature is entirely created by the 3 Heights PDF Security API Acryptographic part A digital signature is based on a cryptographic checksum hash value calculated from the content of the document that is being signed If the document is modified at a later time the computed hash value is no longer correct and the sig
41. E optional See separate chapter on creating a vi sual appearance Proxy Configuration If a proxy is used for the connection to the service see chapter How to Use a Proxy for more information This parameter is not used for certificate selection but for the signature appearance and signature description in the PDF only O PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 35 71 5 5 7 Swisscom All in Signing Service General Properties To use the signature service the following general properties have to be set Description Required Value Setting ete Neue required Name of the signer Property Name Provider required The service endpoint URL of the REST Property Provider service Example https ais swisscom com AIS Server rs v1 0 sign Time stamp optional Varn ietf r c 3161 Property TimeStampURL LOVITE optional trueto embed OCSP responses Property EmbedRevocationInfo If a proxy is used for the connection to the service see chapter How to Use a Proxy for more information Provider Session Properties In addition to the general properties a few provider specific session properties have to be set There are two types of properties String Properties String properties are set using method SetSessionPropertyString File Properties File properties are set using method SetSessionPropertyString with a file name parameter Alternatively the file can be passed in memor
42. F Technology PDF Security API Version 4 5 August 26 2015 44 71 Validation of a PAdES LTV Signature Verifying if a signature conforms to the PAdES LTV standard is similar to validating a Qualified Electronic Signa ture The following must be checked Trust Chain Revocation information Time stamp LTV expiration date Other PAdES Requirements WM PWN gt Trust Chain Trust chain validation works the same as for validating Qualified Electronic Signatures Revocation information Revocation information OCPS response or CRL must be valid and embedded into the signature In the details verify that the revocation check was performed using data that was was embedded in the signature Revocation information that was contained in the local cache or was requested online is not embedded into the signature and does not meet PAdES LTV requirements Time stamp A Time stamp must be embedded and validated as described for validating Qualified Electronic Signatures If a document contains multiple Time stamps all but the latest one must contain revocation information LTV expiration date The long term validation ability expires with the expiration of the signing certificate of the latest Time stamp The life time of the protection can be further extended beyond the life of the last Time stamp applied by adding further DSS information to validate the previous last Time stamp along with a new Time stamp Other PAdES
43. FSecurel GetPDF PDFSecure2 SaveAs OutputFile PDFSecure2 Close This call sequence of course does not make much sense It s merely used to illustrate how to use of the in memory functions In a real application the in memory document is read from another application or a database O PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 46 71 5 9 Stamping The 3 Heights PDF Security API can add new content such as text or images to the output document This process is called stamping The content of previously applied stamps can be modified The 3 Heights PDF Security API can sign and stamp documents in one step In order to not invalidate existing signatures stamps can be modified and created using stamp annotations with an incremental update to the input document An example of this can be seen in the screenshot below T stamp and sign pdf Adobe File Edit View Window Help amp Rev 2 Signed by PDF Tools Support lt pdfsupport pdf tools com gt Annotations Created Annotations Modified E Rev 3 Signed by PDF Tools Support lt pdfsupport pdf tools com gt O PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 47 71 Stamp File Syntax Stamps are described with xml data that is passed to the 3 Heights PDF Security API either as file using the method AddStamps or
44. I 1 60 ME Heights TM PDF Secure API 1 60 3 Heights TM PDF Split Merge API 1 50 3 Heights TM PDF To Image API 1 60 3 Heights TM PDF to PDF A Converter API 1 60 3 Heiohts TM PDF Validator API 1 60 e 4 Help E pur 3 Heights TM PDF Secure API 1 60 Location D Bin bin PdfSecureAPI dll Language Standard 2 Draw anew Command Button and optionally rename it if you like 3 Double click the command button and insert the few lines of code below All that you need to change is the path of the file name Example Private Sub Command1_Click Dim Secure As New PDFSECUREAPILib PdfSecure Secure Open C input pdf Secure SaveAs C output pdf pwd ePermPrint 40 Secure Close End Sub And that s all four lines of code Create the object open the input file create the output file with no user password owner password owner allow printing and use 40 bit encryption key Example More advanced The following Visual Basic 6 sample assumes an interface with Text fields txt for the input and output file names as well as the passwords Check boxes chk with a value to be set to 0 or 1 for all the permission flags Private Sub CreateQutput_Click Dim doc As New PDFSECUREAPILib PdfSecure Dim iPerm As Integer done doc Open txtInput Text txtPwd Text Open the input file If Not done T
45. ME types PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 42 71 5 7 How to Validate Digital Signatures Validation of a Qualified Electronic Signature There are basically three items that need to be validated 1 Trust Chain 2 Revocation Information optional 3 Time stamp optional Validation can be in different ways e g Adobe Acrobat from which the screenshots below are taken Trust Chain Before the trust chain can be validated ensure the root certificate is trusted There are different ways to add a certificate as trusted root certificate The best way on Windows is this 1 Retrieve a copy of the certificate containing a public key This can be done be requesting it from the is suer your CA or by exporting it from an existing signature to a file CertExchange cer Ensure you are not installing a malicious certificate 2 Add the certificate to the trusted root certificates If you have the certificate available as file you can simply double click it to install it After that you can validate the signature e g by open the PDF document in Adobe Acrobat right click the signature and select Validate then select Properties and select the tab Trust There the certificate should be trusted to sign documents or data Certificate Viewer This dialog allows you to view the details of a Certificate and its entire issuance chain The details shown correspond to
46. Owner pwd Encrypt User pwd Owner pwd Permissions Decrypted eee Encrypted PDF PDF In the next step application specific operations are applied These can be setting new passwords and access permissions or add a digital signature not shown in graphic After that a new PDF document is created according to the defined settings In this manual the new resulting document is referred to as output document The input document is never changed by the 3 Heights PDF Security API Thus the output document must be a new document It is not possible to directly overwrite the input document 5 3 Encryption Encryption and how it works in PDF A PDF document can be encrypted to protect its contents from unauthorized access The encryption process applies encryption to all streams e g images and strings but not to other items in the PDF document This means the structure of the PDF document is accessible but the content of its pages is encrypted When encryption is used in PDF a security handler must be selected The 3 Heights PDF Security API always uses the standard security handler which according to the PDF Specification has to be supported by any soft ware that can process encrypted PDF documents For more detailed information about PDF encryption in general see PDF Reference chapter 3 5 PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 23 71 Owner Password and User Pass
47. P UX FreeBSD and others The Unix version of the 3 Heights PDF Security API provides two interfaces Java interface Native C interface Here is an overview of the shared libraries and other files that come with the 3 Heights PDF Security API Table File Description Description bin libPdfSecureAPI so This is the shared library that contains the main functionality The file extension varies depending on the UNIX platform doc Documentation bin SECA jar Java API archive include h Contains files to include in your C C Project PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 9 71 Example code written in different programming languages are available at product page of the PDF Tools AG website http www pdf tools com All Unix Platforms 1 Unpack the archive in an installation directory e g opt pdf tools com 2 Copy or link the shared object into one of the standard library directories e g ln s opt pdf tools com bin libPdfSecureAPI so usr lib 3 Verify that the GNU shared libraries required by the product are available on your system On Linux ldd 1ibPdfSecureAPI so OnAIX dump H 1ibPdfSecureAPI so In case you have not installed the GNU shared libraries yet proceed as follows a Go to http www pdf tools com and navigate to Support Resouces b Download the GNU shared libraries for your platform c Extract the archive and copy or li
48. PageNo and Rect Color See properties FillColor and StrokeColor Line Width The line width of the background rectangle see property LineWidth Text Two text fragments can be set using two different fonts and font sizes see properties Text1 Text2 Font Name1 FontName 2 FontSize1 and FontSize2 Background image See property ImageFileName 5 6 6 Guidelines for Mass Signing This section provides some guidelines for mass signing using the 3 Heights PDF Security API Keep the session to the security device open for multiple sign operations Creating and ending the session to the security device is a complex operation By re using the session for multiple sign operations performance can be improved Create a PdfSecure object Open the session to the provider using BeginSession Use the PdfSecureobject to sign multiple documents Close the session to the provider using EndSession Dispose of the PdfSecure object U BW NES Signing concurrently using multiple threads The 3 Heights PDF Security API is thread safe Each PdfSecure object should be used in one thread at the time only It is recommended that each thread has a separate PdfSecure object The performance improvement when signing concurrently using multiple threads depends mainly on the se curity device used Typically the improvement is large for HSMs and small for USB Tokens Thread safety with a PKCS 11 provider The PKCS 11 standard specifies that an application
49. RA RARA A A ee A 61 DocumentHasBeenModified o o 61 EMail ai A a oa Maes Bee ec as rare 61 EimbedRevocation Into wo a A A as 61 EEG ta ais a ic a a accel tea aa o ab io laca acid le ed 62 Filter ee eee ee AE A A A a A A EE ee ao 62 FontNamel 228 3 kia i a ee a ae el A E Ghee bes ela ae A ee BH ae ee 62 FONtNAME s asrar a oe RRR AE RES A eS A we PGS AA AR ee Re es 62 FOAtSIZET OA NA 63 FON SIZOZ maea pea inc di BR AG ede Be RA ey a eR Ge We ee ale A ks BES 63 FasSIgnature 00 cae ard aa a WEA A SRE ek Oe anne BS E oe We ee RA Bae te aw goals He 63 Imagerille Name gas She oe oP Ree tok a EE ERS Bee PREG bende BEER de A EAE eed 63 ISSUE o rre GOD ERA RROD ED RRR A AA eR Dae ee pa ee ea ee aes 63 LIME WIdt lt 6 3 8 eh e PE wees ES a as ae Eee SS RE A GS BED BOE Sah dees 63 Location shoei Mec a a a Be hw Bem a a A a a wok ae ala lee Bodo aoe des 64 Nam ass cee Se he ead cat ith dean pe ae Ada adie SR Da Ad OO Be Bede Wig id Gh eas Mirae cs 64 PAgeNoO 500 006 bg eae pa PU als MO A ae ee ee ee AY ets Gon Kn RS A Ro as a 64 Provider sai e A EO we ee a ek A we RA A A Le Ge a 64 ProxyURL ticos ir Gok Gai re be aot he Ew eee BES cba ai e Sere Be ee ae eS ee de 65 ProxyCred ntialS lt ss orientar R ES PRG aT ERE DERG E GREER ORE ERR ES Ee SEE 65 REASON ised Sore o A A tie ee A ate aang UR ae Shee dela E Sheds shy Gna ed Sh ae eg eG tea A new ee 65 REGU ieee Sack a aaa aE Ge eb a alle ae iA ae Slow om la a ah eae hae fe BE
50. Requirements Certain other PAdES requirements such as requirements on the PKCS 7 CMS cannot be validated using Adobe Acrobat For this use the 3 Heights PDF Security API for validation See method ValidateSignature of the PdfSecure interface PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 45 71 5 8 Advanced Guide How to Use the in Memory Functions The 3 Heights PDF Security API always requires two PDF documents A PDF input document from which it reads and a PDF output document to where the result is saved to To open from and save to files the functions Open and SaveAs are used These two functions are described in the chapters How to read an encrypted PDF and How to encrypt a PDF Instead of accessing files the documents can be read from and written to in memory The corresponding functions are OpenMem and SavelnMemory l Fil Fi nput File Open SaveAs Output File Encrypt OpenMem SavelnMemory 3 Heights PDF Security API Memory Once the output document is saved to memory using SavelnMemory that memory block can be accessed using the function GetPDF A call sequence to create a first PDFSecure object that opens a PDF from file and stores its output inmemory and then a second object which reads that in memory document and saves it back to a file looks like this PDFSecurel1 Open InputFile PDFSecurel SavelnMenmory PDFSecure1 Close PDFSecure2 0penMem PD
51. SecureAPI 1lib Req samples Doc Doc Doc Doc The purpose of the most important distributed files of is described in Table File Description Table File Description Description bin PdfSecureAPI dl1 This is the DLL that contains the main functionality required binXpdcjk d11 This DLL contains support for Asian languages It is loaded from the module path bin NET d11 The NET assemblies are required when using the NET interface The files binY NET xml contain the corresponding XML documentation for MS Studio include pdferror h Supplementary C header file containing error codes doc Various documentations include Contains files to include in your C C project jar SECA jar The Java wrapper lib PdfSecureAPI lib The Object File Library needs to be linked to the C C project samples Contains sample programs in different programming languages Deployment For the deployment of the software only a subset of the files are required Which files are required Req optional Opt or not used empty field for the four different interfaces is shown in the table below Table Files for Deployment NET JNI COM C binYPdfSecureAPI d11 Req Req Req Req bin pdcjk dl1l Opt Opt Opt Opt binX NET d11 Req jar SECA jar Req The deployment of an application works as described below Identify the required files from your developed application this may also include color profiles Identify
52. T atk ai aE wast oe a eae We Sk alge ed els 65 REVISION eco ci e ith sie Ge id ars Sh Rh yc cai ee Aah tah wh Ge eed te Po Me OS Be Hee Wa he Gee ae ees 66 SerialNumber s gre ia Peas Gee ee a ea ae a a ees AA ae 66 SignerFingerpriNt s ach Ask Gea Gh BS OS ee E Dale Se ee A A AA A a he ea aes 66 SignNerFiINSerprintStr ao ico a eed Sra A Ee eto SME ae dr SE o Beenie oa Ew ee ed 66 STOTE vas Asie ates os taa eC ak a Rome Ph cee Mae nad AAA BO BAR AOS Wen deme a wea ae ae 66 StoreLOcation ti we a A Ge ee ee te ee ek aes eho ee a a eG ee ae ee Re ae a 66 SHOKECOION sti a A ee Blew as ic a a quad a cota aa ae adieu a Bes 67 SUBFINGr Ss 3 bo ee Oe A Rae ode eae ea Pe a AOE Bee wea a a ee Ee A AR 67 VOX a Bae oh as HE Raat we Ba oh ae ee Be ae es OE ee ee 67 TOXEZ a AR OR ee RASS Pale Se Gee Be A a sae es Be ee ees 67 TimeStampCredentialS sa 2 4 cd ob4 ned enh tas 4a bob da bak Bah eas 68 TimeStampriNgerpriMt s sneg ane au ade Re anad a slap dng a eae a AA es ee We eee Gow pe ea G 68 HIMES tampU REx ao BR we RA fe wee aed aoe a So oe A EE O AAA ae a 68 63 TEMUIMCCAUONS cara a aisla Aia Dai Ad aaah alana aah 69 TIPDEERrORGOG Ciszek ia ic ts ol Pi EA A t E 69 TPDEPEFMISSION 4000000 a eG AA E A A RAR ARA AAA o 70 O PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 2 71 7 Licensing and Copyright ooooooooocnnnnnnraooocoooorooo ooo caco oo 71 8 CONTAC vaciadas di ss id e A ii 71 1 Introd
53. aceholder for a signature 4 If the preview PDF is approved the document is signed using a certificate 5 Anew signed PDF output document is created which looks identical to the preview PDF 6 The input document is closed O PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 38 71 5 6 3 How to Create a PAdES LTV Signature In order to create a PACES LTV signature the following is required 1 An advanced or qualified signing certificate For requirements and preparation steps see the sample in chapter Digital Signatures Make sure the store of your cryptographic provider contains all certificates of the trust chain including the root certificate 2 Embed revocation information Do not set the property EmbedRevocationInfo to false 3 Add a Time stamp Use the property TimeStampURL 4 Proper error handling A proper error handling is crucial in order to ensure the creation of correctly signed documents The output document was signed successfully if and only if the method SaveAs returns true and the property ErrorCode does not have any of the following values SIG_CREA_E_OCSP SIG_CREA_E_CRL or SIG_CREA_E_TSP 5 6 4 How to Create a Time stamp Signature For a Time stamp signature no local signing certificate is required Instead the Time stamp signature requested from the Time stamp Authority TSA is embedded into the document Example Create a Time stamp signature using the method AddTimeSta
54. all files that are required by your developed application Include all these files into an installation routine such as an MSI file or simple batch script Perform any interface specific actions e g registering when using the COM interface PUNS PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 12 71 Example This is a very simple example of how a COM application written in Visual Basic 6 could be deployed 1 The developed and compiled application consists of the file securer exe Color profiles are not used 2 The application uses the COM interface and is distributed on Windows only The main DLL PafSecureAPI dll must be distributed Asian text should be supported thus pdcjk di is distributed 3 All file are copied to the target location using a batch script This script contains the following commands COPY PdfSecureAPI dll targetlocationyZ COPY pdcjk dll targetlocationZ 4 For COM the main DLL needs to be registered in silent mode s on the target system This step requires Power User privileges and is added to the batch script REGSVR32 s targetlocation PdfSecureAPI d1l 2 4 Interface Specific Installation Steps COM Interface Registration Before you can use the 3 Heights PDF Security API component in your COM application program you have to register the component using the regsvr32 exe program that is provided with the Windows operating system The following command shows
55. cannot display an encrypted text or image without first decrypting it A PDF application program has therefore full access to any PDF document it can decrypt and display PDF application programs such as all products of the PDF Security API family or Adobe Acrobat can open and decrypt PDF documents which have an owner password but no user password without knowing that password Otherwise they couldn t display the document The application at that point has full access to the document However this does not imply the user of this application is given the same access rights The user should only be given the access permissions defined by the permission flags and the password he provided Any PDF application which behaves different from that can allow for changing the security settings or completely removing encryption from the document as long as the original document does not have a user password The user password protects the document so that it only can be opened if the user or owner password is known No PDF application program can open a user password protected PDF document without providing the password The security of such a document however strongly depends on the password itself Like in most password related situations insecure passwords can easily be found programmatically E g a brute force attempt testing all passwords which either exist as word in a dictionary or have less than six characters only takes minutes 5 4 Fonts Some featu
56. ce Standards ISO 32000 PDF 1 7 ISO 19005 1 PDF A 1 ISO 19005 2 PDF A 2 ISO 19005 3 PDF A 3 PAdES Part 2 and Part 4 Long Term Validation LTV PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 4 71 1 3 Interfaces The following interfaces are available C Java NET COM 1 4 Operating Systems Windows XP Vista 7 8 8 1 32 and 64 bit Windows Server 2003 2008 2008 R2 2012 2012 R2 32 and 64 bit HP UX 11 and later PA RISC2 0 32 bit or HP UX 11i and later a64 Itanium 64 bit IBMAIX 5 1 and later 64 bit Linux 32 and 64 bit MacOSX 10 4 and later 32 and 64 bit Sun Solaris 2 8 and later SPARC and Intel FreeBSD 4 7 and later 32 bit or FreeBSD 9 3 and later 64 bit on request 1 5 Howto Best Read this Manual If you are reading this manual for the first time e would like to evaluate the software the following steps are suggested Read the chapter Introduction to verify this product meets your requirements Identify what interface your programming language uses Read and follow the instructions in the chapter Installation And Deployment In the chapter Programming Interfaces find your programming language Please note that not every lan guage is covered in this manual For many programming languages there is sample code available For a start it is generally best to refer to these samples rather than writing code from scratch 5 Optional
57. code See also enumeration TPDFErrorCode PDF Tools error codes are listed in the header file pdferror h Please note that only few of them are relevant for the 3 Heights PDF Security API ErrorMessage Property String ErrorMessage Accessors Get Return the error message text associated with the last error see property ErrorCode Note that the property is NULL if no message is available EndSession Method Boolean EndSession Ends the opten session to the security device See BeginSession O PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 55 71 ForceEncryption Property Boolean ForceEncryption Accessors Get Set Default False File encryption is not allowed by the PDF A standard Therefore 3 Heights PDF Security API aborts and returns an error when encryption is configured and an input file is PDF A Use this option in order to enable encryption of PDF A conforming files The conformance of the output file is downgraded to PDF ForceSignature Property Boolean ForceSignature Accessors Get Set Default False Force signature allows DocMDP PDF 1 6 and Time stamp signatures PDF 2 0 on PDF A 1 documents The output file s version is upgraded and PDF A conformance removed So the output file will contain the signature but not be PDF A 1 anymore Applying a DocMDP or Time stamp signature breaks PDF A 1 compliance theref
58. ct and re serialized SSLClientCertificate File required SSL client certificate in PKCS 12 Format p12 pfx File must contain the certificate itself all certifi cates of the trust chain and the private key SI Rete ait String optional Password to decrypt the private key of the SLL client certificate SSLServerCertificate File recommended Certificate of the server or its issuer CA certifi cate in DER Format der cer Note If this property is not set the server cer tificate is not verified at all Signature Configuration The signature can be customized using standard properties Description Required Value Setting Common Name required The name ofthe signer should be set Property Name Time stamp optional arn Ghee stes Siglo Property TimeStampURL Revocation Info optional true to embed OCSP responses or Property EmbedRevocationInfo CRL MENEM TIE IEA optional See separate chapter on creating a vi sual appearance 3This parameter is not used for certificate selection but for the signature appearance and signature description in the PDF only O PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 34 71 Proxy Configuration If a proxy is used for the connection to the service see chapter How to Use a Proxy for more information 5 5 6 QuoVadis sealsign Provider Property Provider The provider configuration string contains the URL to the QuoVadis sealsign service
59. d PDF document If this parameter is left out an empty string is used as a default Return value True The file could successfully be opened False The file does not exist it is corrupt or the password is not valid Use the property ErrorCode for additional information OpenMem Method Boolean OpenMem Variant MemBlock String Password Open a PDF document or raster image from memory i e make the objects contained in the document acces sible If a document is already open it is closed first PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 57 71 Parameters MembBlock The memory block containing the PDF file given as a one dimensional byte array Password optional The user or the owner password of the encrypted PDF document If this parameter is left out an empty string is used as a default Return value True The document could successfully be opened False The document could not be opened it is corrupt or the password is not valid RevisionCount Property Integer RevisionCount Accessors Get Return the number of revisions of the document the number of incremental updates Although a linearized file looks like an incrementally updated file it only counts as one revision See also GetRevision SaveAs Method Boolean SaveAs String FileName String UserPw String OwnerPw TPDFPermission PermissionFlags Long KeyLength String StrF
60. dified by applying the following stamp xml file to the output file of the example above Note that since position and size of the stamp remain unchanged the respective attributes can be omitted lt xml version 1 0 encoding utf 8 gt lt ps pdfstamp xmlns ps http www pdf tools com pdfstamp gt lt ps stamp name simple stamp gt lt ps filltext align left middle fontencoding WinAnsi font Arial size 12 text Modified Stamp gt lt ps stamp gt lt ps pd stamp gt Example Add a watermark text diagonally across page Note an A4 page is 595 by 842 points lt xml version 1 0 encoding utf 8 gt lt ps pdfstamp xmlns ps http www pdf tools com pdfstamp gt lt ps stamp page all size 595 842 align center middle scale relToA4 autoorientation true type foreground gt lt ps rotate angle 55 origin 298 421 gt lt ps stroketext align center middle position 298 421 font Arial Bold size 60 text WATERMARK TEXT gt lt ps rotate gt lt ps stamp gt lt ps pd stamp gt O PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 52 71 Example Apply stamp to long edge of all pages Stamp has a light gray background and a black border lt xml version 1 0 encoding utf 8 gt lt ps pdfstamp xmlns ps http www pdf tools com pdfstamp gt lt ps stamp page all size 802 12 relativepos 5 0 align middle rota
61. directory for temporary files OCSP responses ocsp server hash der CRL crl server der TSP responses tsp server der Service data sig hash bin The caches can be cleared by deleting the files Usage ofthe caches can be deactivated by setting the NoCache flag The files are updated if the current date and time exceeds the next update field in the OCSP or CRL response respectively or the cached data was downloaded more than 24 hours ago The directory for temporary files is determined as follows The product checks for the existence of environment variables in the following order and uses the first path found Windows 1 The path specified by the TMP environment variable 2 The path specified by the TEMP environment variable 3 The path specified by the USERPROFILE environment variable 4 The Windows directory Unix 1 The path specified by the PDFTMPDIR environment variable 2 The path specified by the TMP environment variable 3 The tmp directory How to Use a Proxy The 3 Heights PDF Security API can use a proxy server for all communication to remote servers e g to down load CRL or for communication to a signature service The proxy server can be configured using the provider session property Proxy The property s value must be a string with the following syntax http s lt user password gt host lt port gt Where http https Protocol for connection to proxy user password optional Credential
62. e cryptographic provider yourself you can register a Custom Signature Handler This is described in the respective subsection 5 5 1 PKCS 11 Provider PKCS 11 is a standard interface offered by most cryptographic devices such as HSMs USB Tokens or sometimes even soft stores e g openCryptoki More information on and installation instructions of the PKCS 11 provider of various cryptographic devices can be found in the separate document TechNotePKCS11 pdf Configuration Provider Property Provider The provider configuration string has the following syntax PathToD11 SlotId Pin PathToD11 is the path to driver library filename which is provided by the manufacturer of the HSM UBS token or smart card Examples The SuisselD USB Tokens use cvp11 dll The CardOS API from Atos Siemens uses siecap11 dll The IBM 4758 cryptographic coprocessor uses cryptoki dll Devices from Aladdin Ltd use etpkcs11 dll lotId is optional if it is not defined it is searched for the first slot that contains a running token Pin is optional if it is not defined the submission for the pin is activated via the pad of the token If this is not supported by the token the following error message is raised when signing Cannot access private key Examples Provider WINDOWS system32 siecap11 d11 4 123456 Note Some PKCS 11 drivers require the Terminate method to be called Otherwise your application might crash upon termination
63. en aon saw ea Ale ed AAA be a deals aa ee Ea 08 18 5 USEr S GUIDE vv is Sie 8 ee ER a Oo OG BROS Sb BOR ES OR BBE BLES we 20 5 1 Overview ofthe APL 2 ee ee eee eee 20 5 2 How does the API workin general 2 2 ee 21 93 ENE PUOM ica and o A dd yee a An 21 S4 A NO 23 5 5 Cryptographic Provider oss soa aaa Rig ic a a Gage Ra aE awa lane Ae woud ate aud 24 PRCSPIAIRKOVIdER fos Bue ae as a ane eds Sues OO At SS 25 Microsoft CryptoAPI Provider ac05 0245088 be eA aE ERS be Oe ER AE wr ea ee eae o 26 3 Heights Signature Creation and Validation Service o eee 29 SwissSign Personal Signing Service eee 31 SwissSign SulsselD Sigming SERVICE ari a sik ek ce aoe ke e es Rare GPR oe eo aad A A 32 QuoVadis sealsign ee ee 33 Swisscom All in Signing Service 2 eee 34 Custom Signature Handler ias See ges ES u eG ASS e Oe A Oe eae ah ee ee ed 35 5 6 Howto Create Digital Signatures 1 eee eee 35 How to Signa PDF Document 4 034644 58 a DEER De TERRA REE ER GREE TE Re ee 36 How to create a Preview of a Signed Document 20 0 ee ee 36 How to Create a PAGES LTV Signature ee 37 How to Create aTime stamp Signature seeen eene 37 How to Create a Visual Appearance of a Signature uaaa o 37 Guidelines for Mass SigNiNdg_ ee eee ees 38 Miscellaneous si uta bai bea nt fea we hh ee ba ia eRe eh eee Se SSS Hee heed 39 5 7 How to Validate Digital Signatures 1 ee 41 5 87 AGVAN
64. en applied the signature becomes invalid However the person who applied the changes could at the same time maliciously also remove the existing simple electronic signature and after the changes apply a new equally looking Simple Electronic Signature and falsify its date As we can see a simple electronic signature is neither strong enough to ensure the integrity of the document nor to authenticate the signer This drawback can be overcome using an Advanced or Qualified Electronic Signature Advanced Electronic Signature Requirements for advanced certificates and signatures vary depending on the country where they are issued and used An advanced electronic signature is based on an advanced certificate that is issued by a recognized certificate authority CA in this country such VeriSign SwissSign QuoVadis In order to receive an advanced certificate its owner must prove his identity e g by physically visiting the CA and presenting his passport The owner can be an individual a legal person or another entity An advanced certificate contains the name of the owner the name of the CA its period of validity and other information The private key of the certificate is protected by a PIN which is only known to its owner This brings the following advantages over a simple electronic signature The signature authenticates the signer The signature ensures the integrity of the signed content Qualified Electronic Signature
65. eps need to be done 1 Create a new PdfSignature object 2 As value of the PdfSignature s name the name of the certificate that is to be used must be provided The name of the certificate corresponds to the value Issued to 3 If the certificate s private key is PIN protected the PIN can be passed in the provider configuration 4 Additional parameters can now be set such as the reason why the signature is applied etc In Visual Basic the four steps above look like this Dim Document As New PDFSECUREAPILib PdfSecure Document Open input pdf Dim Signature As New PDFSECUREAPILib PdfSignature Signature Name Philip Renggli Signature Provider cvp11 d11 0 secret pin Signature Reason I reviewed the document optional Signature TimeStampURL http server mydomain com 80 tsa optional Document AddSignature Signature Document SaveAs output pdf Document Close Note On Non Windows platforms additional settings are required to be set such as fonts The visual appearance of the digital signature on a page of the resulting output document looks as shown below PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 8 71 ip Renggli Digitally eal by 99 Philip Renggli Reason reviewed the document Time D 20061211132331 2 Installation and Deployment 2 1 Windows The retail version of the 3 Heights PDF Security API comes as a ZIP archive
66. ersion 4 5 August 26 2015 69 71 TimeStampCredentials Property String TimeStampCredentials Accessors Get Set Default If a Time stamp server requires authentication use this property to provide the credentials Credentials com monly have the syntax username password TimeStampFingerprint Property Variant TimeStampFingerprint Accessors Get The sha1 fingerprint of the Time stamp server certificate After validating a signature that contains a Time stamp this property contains the fingerprint of the Time stamp server s certificate TimeStampURL Property String TimeStampURL Accessors Get Set Default The URL of the trusted Time stamp authority TSA from which a Time stamp shall be acquired This setting is suggested to be used when applying a Qualified Electronic Signature Example tsu my timeserver org Apply ing a Time stamp requires an online connection to a time server the firewall must be configured accordingly In case a web proxy is used it must be ensured the following MIME types are supported application timestamp query application timestamp reply Ifan invalid Time stamp server address is provided or no connection can be made to the time server the return code of SaveAs is true and the property ErrorCode is set to SIG_CREA_E_TSP after calling SaveAs O PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 70 71 6
67. ertificate store defined by the provider is used Within the store the selection of the signing certificate works the same as with the PKCS 11 provider which is described here Selecting a Certificate for Signing Certificates In order to sign a PDF document a valid existing certificate name must be provided and its private key must be available There are various ways to create or obtain a certificate How this is done is not described in this document This document describes the requirements for and how to use the certificate On the Windows operating system certificates can be listed by the Microsoft Management Console MMC which is provided by Windows In order to see the certificates available on the system do the following steps T O E uN O PDF Tools AG Premium PDF Technology To launch the MMC go to Start gt Run gt type mmc or start a Command Prompt and type mmc A a Type the name of a program folder document or Internet resource and Windows will open it For you Open y Cancel Browse Under File gt Add Remove Snap in Choose Certificates and click the Add button In the next window choose to manage certificates for My user account Click Finish The certificate must be listed under the root Certificates Current User for example as shown in the screenshot below fx D c ulala
68. es the requirements listed in the previous chapter it has the additional requirement to contain the key Authority Information Access which contains the information about the OCSP server Certificate General Details Certification Path Show lt All gt v Field Value certificate Policies 1 Certificate Policy Policy Ide 5 Authority Information 4 1 Authority Info Access Acc le Subject Alternative Name Other Name 1 3 169 13 12 4 Falissuer Alternative Name Directory Address O ZertES Esauthority Key Identifier KeyID 3a 52 64 Ob da ee 4c 5 Falcrt Distribution Points 1 CRL Distribution Point Distr FA subject Key Identifier 9a 00 d3 56 43 41 6e a0 e6 5d Flkey Usage Digital Signature Non Repudia Access Method On line Certificate Status Protocol 1 3 6 1 5 5 7 48 1 Alternative Name URL http focsp quovadisglobal com 2 Authority Info Access Access Method Certification Authority Issuer 1 3 6 1 5 5 7 48 2 Alternative Name URL http trust quovadisglobal com qvtsagca crt v Edit Properties Copy to File 5 5 3 3 Heights Signature Creation and Validation Service The 3 Heights Signature Creation and Validation Service provides HTTP protocol based remote access to cryp tographic providers such as smartcards USB tokens and other cryptographic infrastructure such as HSMs Use of the 3 Heights Signature Creation and Validation Service pr
69. filltext See filltext 8Prior to version 4 4 31 0 of the 3 Heights PDF Security API position specified the origin of the first character When upgrading add 0 75 size to the value of y PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 50 71 ps image rect x ywh filename path compression value ps fillrectangle rect x ywh color r g b alpha t ps strokerectangle rect x ywh linewidth f color r gb alpha t Notes Add Image In order for the stamp to be PDF A compliant the image s color space must match the document s output intent s The rectangle where the image is to be placed at x y correspond the the location origin at lower left corner and w h to width and height e g 100 200 50 50 The path to the file e g CApicturestimage jpg By default bi tonal images are compressed with CCITTFax continuous tone images with DCT and indexed images with Flate To explicitly set the compression use this property Support values are Flate Flate encoded DCT DCT JPEG encoded CCITTFax CCITT G4 encoded Add Filled Rectangle The coordinates and size of the rectangle If this value is omitted the rectangle fills the area of the stamp The fill color of the rectangle The color as RGB value where all values must be from Oto 1 The opacity of the rectangle 1 0 for fully opaque 0 0 for fully transparent Default 1 0 The PDF A 1 standard does not allow t
70. he key length can be any value from 40 to 128 that is a multiple of 8 For AESV2 the key length is automatically set to 128 for AESV3 to 256 Notes Certain PDF viewers only support 40 and 128 bit encryption Other tools such as the 3 Heights tools also support other encryption key lengths 256 bit encryption requires Acrobat 9 or later Ifthe selected permission flags require a minimum key length the key length is automatically adjusted e g to 128 bits StrF optional Default V2 Set the string crypt filter Supported values are None V2 default RC4 AESV2 and AESV2 Setting this value to an empty string or null means the default filter is used Supported crypt filter None The application does not decrypt data V2 or RC4 PDF 1 2 The application asks the security handler for the encryption key and implicitly decrypts data using the RC4 algorithm AESV2 PDF 1 6 The application asks the security handler for the encryption key and implicitly decrypts data using the AES V2 128 bit algorithm AESV3 PDF 1 7 The application asks the security handler for the encryption key and implicitly decrypts data using the AES V3 256 bit algorithm StmF optional Default V2 Set the stream crypt filter Supported values are None V2 RCA AESV2 and AESV3 Note that certain viewers require the stream crypt filter to be equal to the
71. he position in points in the stamp e g 200 300 With the default align values align left top position defines the left top corner of the text Align text at position or stamp if position is not set Values for horizontal alignment xalign left align to the left default center center text right align to the right Values for vertical alignment yalign top align to the top default middle align to the middle bottom align to the bottom Example align left bottom positions the text in the left bottom corner of the stamp If position is set align left bottom corner of text to position The true type name of the font e g Arial Or Times New Roman Bold or a complete path to the font e g C Windows Fonts Arial ttf If the name is used the respective font must be available in any of the font directories see chapter Fonts The font size in points e g 12 If set to O the size is chosen such that text fits stamp size not allowed if operator is within transformation operator Encoding of the font Allowed values are Unicode default and WinAnsi see note 3 below The text that is to be written e g text Hello World Multiline text is supported by using the newline character amp 10 e g text 1st line amp 10 2nd line Add Stroked Text Outlined Text For parameters see filltext Set the linewidth in points e g 1 0 See filltext See filltext See filltext See filltext See filltext See
72. hen If doc ErrorCode PDF_E_PASSWORD Then MsgBox Input file is encrypted and Password not correct Else O PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 17 71 MsgBox Couldn t open input file End If Exit Sub End If Set the permissions iPerm chkPrint Value ePermPrint chkModify Value ePermModify chkCopy Value ePermCopy chkAnnot Value ePermAnnotate chkFill Value ePermFillForms chkExtr Value ePermSupportDisabilities chkAssemble Value ePermAssemble chkDPrint ePermDigitalPrint iKey 128 Save the output file If Not doc SaveAs txtOutput Text txtUser Text txtOwner Text _ iPerm iKey Then MsgBox Output file could not be created End If done doc Close End Sub PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 18 71 4 2 C C In order to use the 3 Heights PDF Security API in a C project the following steps should be done Note Steps and Screenshots are specifically described for the MS Studio 6 Add the header files PdfSecureapi_c h and pdfsecuritydecl h to the include directories 1 2 Link to the object file library Windows PdfsecureAPI lib 21x Settings For win32 Debug General Debug C C Link Resourct ERE pdisecure EY Source Files E pdfsecure c Header Files Resource Files Category General Reset Output file name o ebug pdfsecure exe
73. icense keys are stored in the file system etc opt pdf tools for all users pdf tools for the current user Note The user group and permissions of those directories are set explicitly by the license manager tool It may be necessary to change permissions to make the licenses readable for all users Example chmod R gotrx etc opt pdf tools O PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 16 71 4 Programming Interfaces 4 1 Visual Basic 6 After installing the 3 Heights PDF Security API and registering the COM interface see chapter Download and Installation you find a Visual Basic 6 example PdfSecureAPl vbp in the directory samples VB You can either use this sample as a base for an application or you can start from scratch If you start from scratch here is a quick start guide for you 1 First create a new Standard Exe Visual Basic 6 project Then include the 3 Heights PDF Security API com ponent to your project References PDFSecureAPLy bp Available References be 3 Heights TM Font To PDF Conversion API 1 60 Cancel 3 Heights TM Image to PDF Converter API 1 60 1 3 Heights TM PDF Annotation API 1 60 3 Heights TM PDF Content To Image API 1 60 Browse 3 Heights TM PDF Export API 1 60 3 Heights TM PDF Optimizer API 1 60 al _ 3 Heights TM PDF Printer API 1 60 _ 3 Heights TM PDF Renderer API 1 60 Priority 3 Heights TM PDF Repair AP
74. ifferent countries The type of electronic signatures required in a certain process is usually defined by national laws Quite advanced in this manner are German speaking countries where such laws and an established terminology exist The English terminology is basically a translation from German Three types of electronic signatures are distinguished Simple Electronic Signature Einfache Elektronische Signatur Advanced Electronic Signature Fortgeschrittene Elektronische Signatur Qualified Electronic Signature QES Qualifizierte Elektronische Signatur All applied digital signatures are PDF A and PAdES compliant PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 6 71 Simple Electronic Signature A simple electronic signature requires any certificate that can be used for digital signing The easiest way to retrieve a certificate which meets that requirement is to create a so called self signed certificate Self signed means it is signed by its owner therefore the issuer of the certificate and the approver of the legitimacy of a document signed by this certificate is the same person Example Anyone could create a self signed certificate issued by Peter Pan and issued to Peter Pan Using this certificate one is able to sign in the name of Peter Pan If a PDF document is signed with a simple electronic signature and the document is changed after the signature has be
75. ing any of the service providers such as the Swisscom All in signing service the value of this property is essentially the url of the service endpoint http s server servicedomain com 8080 url ProxyURL Property String ProxyURL Accessors Get Set Default This property has been deprecated For more information see the chapter How to Use a Proxy ProxyCredentials Property String ProxyCredentials Accessors Get Set Default This property has been deprecated For more information see the chapter How to Use a Proxy Reason Property String Reason Accessors Get Set Default Set or get the descriptive text for why the digital signature was added It is not required in order to create a valid signature If this property is set to an empty string no entry is created Rect Property Variant Rect Accessors Get Set Default 10 10 210 60 Set or get the position and size of the digital signature annotation The default is in the lower left corner The units are PDF points 1 point 1 72 inch A4 595x842 points Letter 612x792 points measured from the lower left corner of the page The position is defined by the four values for the lower left x1 y1 and upper right x2 y2 corner of the rectan gle If either the width or height is zero or negative an invisible signature is created i e no visible appearance is created for the signature To create
76. ional properties have to be set AELIG Required Value Mobile phone number Example 41798765432 SwisscomAllinMSISDN required MURA ESE String required The message to be displayed on the mobile phone Example Pipapo halolu MESA EAE String required The language of the message Example DE Those properties have to comply with the Swisscom Mobile ID specification 5 5 8 Custom Signature Handler The 3 Heights PDF Security API provides the capability of replacing the default built in signature handler with a custom signature handler A custom signature handler has full control over the creation and validation of the cryptographic part of a signature This makes it possible to implement proprietary signing algorithms The custom signature handler must implement a C interface as described in the header file pdfsignaturehandler h It can be registered using a call to PdfRegisterSignatureHandler during the initialization of the 3 Heights PDF Security API When using a custom signature handler it is important that this call be made before using the API for signing This allows for treating the PDF and signature technologies separately and also provides an easy way to replace a signature handler 5 6 How to Create Digital Signatures This chapter describes the steps that are required to create different types of digital signatures A good intro ductory example can be found in the chapter Digital Signatures PDF Tools
77. ired For most automated processes an ad vanced signature is sufficient 2 Acquire a corresponding certificate from a CA Note that some CA offer USB sticks or smart cards that contain both an advanced and a qualified certificate 3 Setup and configure the certificate s Cryptographic Provider Incase the certificate resides on hardware such as an USB token or a Smart Card the required middle ware driver needs to be installed Incase the certificate is a soft certificate it must be imported into the certificate store of a cryptographic provider 4 Optional Acquire access to a trusted time server TSA e g from the CA of your signing certificate 5 Apply the signature by providing the following information Values for the selection of the signing certificate e g the name of the certificate The Cryptographic Provider where the certificate is located Optional Time stamp service URL e g http server mydomain com 80 tsa Optional Time stamp service credentials e g username password Optional Embed revocation information default true Optional Visual appearance of the signature on a page of the document e g an image Example Steps to Add an Electronic Signature The 3 Heights PDF Security API applies PDF A compliant signatures This means if a PDF A document is digi tally signed it remains PDF A compliant In order to add an electronic signature with the 3 Heights PDF Security API the following st
78. key can be installed for a specific product The checkbox on the left side in the license list marks the currently active license key PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 15 71 3 2 Command Line License Manager Tool The command line license manager tool 1icmgr is available in the bin directory for all platforms except Windows A complete description of all commands and options can be obtained by running the program without param eters licmgr List all installed license keys licmgr list Add and delete license keys Install new license key licmgr store X XXXXX XXXXX XXXXX XXXXX XXXXX XXXXX Delete old license key licmgr delete X XXXXX XXXXX XXXXX XXXXX XXXXX XXXXX Both commands have the optional argument s that defines the scope of the action g For all users ut Current user Select between different license keys for a single product licmgr select X XXXXX XXXXX XXXXX XXXXX XXXXX XXXXX 3 3 License Key Storage Depending on the platform the license management system uses different stores for the license keys Windows The license keys are stored in the registry HKLM Software PDF Tools AG for all users HKCU Software PDF Tools AG for the current user Mac OS X The license keys are stored in the file system Library Application Support PDF Tools AG for all users Library Application Support PDF Tools AG for the current user Unix Linux The l
79. mpSignature Dim Document As New PDFSECUREAPILib PdfSecure Document Open input pdf Dim Signature As New PDFSECUREAPILib PdfSignature Signature Provider cvp11 d11 Signature TimeStampURL http server mydomain com 80 tsa Document AddTimeStampSignature Signature Document SaveAs output pdf Document Close A Cryptographic Provider is required on non Windows systems only 5 6 5 How to Create a Visual Appearance of a Signature Each signature may have a visual appearance on a page of the document The visual appearance is optional and has no effect on the validity of the signature Because of this and because a visual appearance may cover important content of the page many applications choose to create an invisible signature By default the 3 Heights PDF Security API creates an appearance in the lower left corner of the last page which looks as shown below ip Rengali Digitally pes by 99 Philip Renggli Reason reviewed the document Time D 20061211132331 How to Create an Invisible Signature Invisible signatures have no visual appearance and can be created by setting an empty rectangle using the Property Rect signature Rect New PDFRect 0 0 0 0 PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 39 71 How to Create a Visual Appearance Different properties of the visual appearance can be specified Page and Position See properties
80. nature becomes invalid i e the validation will fail and will report that the document has been modified since the signature was applied Only the owner of the certificate and its private key is able to sign the document However anybody can verify the signature with the pub lic key contained in the certificate This part of the signature requires a cryptographic provider for some cryptographic data and algorithms The 3 Heights PDF Security API supports the following types of digital signatures Document Signature Check the integrity of the signed part of the document and authenticate the signer s identity One or more signatures can be applied A signed document can be modified and saved by incre mental update The state of the document can be re created as it existed at the time of signing MDP Modification detection and prevention Signature Enable detection of disallowed changes specified by the author A document can contain only one MDP signature it must be the first in the document Other document signatures may be present Document Time stamp Signature Establish the exact content of the file at the time indicated by the Time stamp One or more document Time stamp signatures can be applied A signed document can be modified and saved by incremental update 1 6 1 What is an Electronic Signature There are different types of electronic signatures which normally are defined by national laws and therefore are different for d
81. ning Service please contact Swiss Post Solutions AG suisseid post ch to obtain access credentials Prior to invoking the SuisselD Signing Service user authentication via the SuisselD Identity Provider IDP is a pre requisite So the calling application must integrate via SAML e g SuisselD SDK with the SuisselD Identity Provider The IDP issues SAML tokens upon successful user authentication Note that the name of the signature should be the signer s name e g lt givenname gt lt surname gt The signer s name can be retrieved for the SAML token as the IDP provides this as qualified attributes yellowid verified Provider Property Provider The provider configuration string contains the URL to the service Endpoint Provider Configuration The provider can be configured using provider session properties There are two types of properties String Properties String properties are set using method SetSessionPropertyString File Properties File properties are set using method SetSessionPropertyString with a file name parameter Alterna tively the file can be passed in memory as byte array using the method SetSessionPropertyBytes Name Type Required Value SAMLToken File required SAML token issued by the SuisselD Identity Provider IDP Example C temp my sam1 xml Note The SAML token received from the IDP is a signed XML and must not be modified in any way For example the token should not be read into a string or XML obje
82. nk the libraries into your library directory e g usr lib or usr lib64 d Verify that the GNU shared libraries required by the product are available on your system now 4 Optionally register your license key using the Command Line License Manager Tool 5 Identify which interface you are using Perform the specific installation steps for that interface described in chapter Interfaces 6 If you want to sign documents proceed with setting up your cryptographic provider as described in chapter Cryptographic Provider 7 If you want to stamp text proceed with setting the fonts required as described in chapter Fonts MAC OS X The shared library must have the extension nilib for use with Java We suggest that you create a file link for this purpose by using the following command ln libPdfSecureAPI dylib libPdfSecureAPI jnilib PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 10 71 2 3 Interfaces The 3 Heights PDF Security API provides four different interfaces The installation and deployment of the software depend on the interface you are using The table below shows the supported interfaces and examples with which programming languages they can be used Table Interfaces Interface Programming Languages NET The MS software platform NET can be used with any NET capable programming language such as CH VB NET j others This interface is available in the Windows version
83. ocument could be saved in memory successfully False Otherwise SetSessionProperty Method Boolean SetSessionPropertyString String Name String Value Method Boolean SetSessionPropertyBytes String Name Variant Value Provider specific session configuration Properties have to be set before calling BeginSession and are deleted when calling EndSession Parameters Name The name of the property The names that are supported are specific to the provider used with BeginSession Value The value of the property as string or byte array SignatureCount Property Long SignatureCount Accessors Get Return the number of signature fields If 0 is returned it means there is no digital signature in the document PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 60 71 SignPreparedSignature Method Boolean SignPreparedSignature PdfSignature pSignature Create a digital signature for an existing signature field which was previously created using the method Ad dPreparedSignature This method must be called prior to SaveAs or SavelnMemory Parameters pSignature The digital signature that is to be added This must be the same signature as used in AddPreparedSignature Return value True Successfully added the signature to the document False Otherwise SignSignatureField Method Boolean SignSignatureField PdfSignature pSignature
84. oft NET Framework v2 0 50727 S5ystem Windows Forms dll Signing Security Publish Add El Remove Update Web Reference Imported namespaces Pdftools PaF Add User Import Pdftools PdFSecure System System Drawing System Windows Forms Microsoft Microsoft CSharp Microsoft VisualBasic Microsoft VisualBasic ApplicationServices Microsoft VisualBasic CompilerServices xl Update User Import K K S K K 4 The NET interface can now be used as shown below Dim doc As New PdfSecure Secure Dim sig As New PdfSecure Signature doc Open If Not doc SaveAs C temp output pdf nun gt pudl A PDFPermission ePermPrint 128 AO V2 True Then CH 3 Add the following namespaces using Pdftools Pdf using Pd tools PdfSecure 4 The NET interface can now be used as shown below Secure doc new Secure Signature sig new Signature doc Open O PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 21 71 Deploying in NET When deploying a NET solution please refer to the following FAQ Deploying in NET http www pdf tools com pdf Support FAQ Article aspx name Deployment In NET Troubleshooting TypelnitializationException The most common issue when using the NET interface is if the native DLL i
85. only INI The Java native interface JNI is for use with Java COM The component object model COM interface can be used with any COM capable program ming language such as MS Visual Basic MS Office Products such as Access or Excel VBA C VBScript others This interface is available in the Windows version only C The native C interface is for use with C and C Development The software developer kit SDK contains all files that are used for developing the software The role of each file with respect to the four different interfaces is shown in Table Files for Development The files are split in four categories Req This file is required for this interface Opt This file is optional e g Inet dll is used for http and other connections When using the API locally this file is not used See also Table File Description to identify which files are required for your application Doc This file is for documentation only An empty field indicates this file is not used at all for this particular interface Table Files for Development NET JNI bin PdfSecureAPI d11 Req Req Req Req bin pdcjk dl1l Opt Opt Opt Opt binX NET d11 Req binX NET xml Doc doc pdf Doc Doc Doc Doc docXPdfSecureAPI idl Doc O PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 11 71 doc javadoc Doc include pdfsecureapi_c h Req include Opt jar SECA jar Req lib Pdf
86. or to SaveAs or SavelnMemory Do not dispose of the PdfSignature object until the associated document has been saved or closed Parameters pSignature The digital signature that is to be added The properties of the signature must be set before it is added Return value True Successfully added the signature to the document Note At this point it is not verified whether the certificate is valid or not If an invalid certificate is provided the SaveAs function will fail later on False Otherwise AddSignatureField Method Boolean AddSignatureField PdfSignature pSignature Add a signature field only This method adds a field which is meant to be signed manual in a later step This method must be called prior to SaveAs or SavelnMemory Parameters pSignature The digital signature that is to be added The properties of the signature must be set before it is added Return value True Successfully added the signature to the document False Otherwise AddStamps Method Boolean AddStamps String FileName Add a stamp xml file This method must be called after the input file is opened and before the save operation For more information about stamping see the section Stamping AddStampsMem Method Boolean AddStamps Variant MemBlock Add a stamp xml from memory This method must be called after the input file is opened and before the save operation For more information about stam
87. ore the default behavior is to abort the operation with an error GetPDF Method Variant GetPDF Get the output file from memory See also method SavelnMemory Return value A byte array containing the output PDF In certain programming languages such as Visual Basic 6 the type of the byte array must explicitly be Variant GetRevison Method Variant GetRevision Integer iRevision Return the PDF document of a given revision number This is useful to retrieve the state of the PDF document at the time it has been signed All revisions which had been applied after the given revision are ignored Return value The selected revision of the PDF file GetSignature Method PdfSignature GetSignature Long iSignature Get a signature field from the current document Parameters jSignature The selected signature in the document in the range from 0 to n 1 where 0 is the first and n 1 the last signature The total number of signatures in the document can be retrieved using the property SignatureCount which returns a value from 0 to n Return value An interface to the PdfSignature GetSignatureCount Deprecated use the property SignatureCount instead PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 56 71 InfoEntry Property String InfoEntry String Key Accessors Get Set Parameters Key A key as string Return value
88. ort 5 5 2 Microsoft CryptoAPI Provider Microsoft CryptoAPI MS CAPI CAPI offers access to the certificates stored in the Windows certificate store and other devices such as USB tokens with Windows integration Microsoft CryptoAPI does not support some new cryptographic algorithms Therefore it is recommended to use the PKCS 11 Provider if possible Configuration Provider Property Provider The provider configuration string has the following syntax ProviderType Provider PIN The ProviderType and PIN are optional The corresponding drivers must be installed on Windows Examples Provider Microsoft Base Cryptographic Provider v1 0 Provider Microsoft Strong Cryptographic Provider Provider PROV_RSA_AES Microsoft Enhanced RSA and AES Cryptographic Provider The provider type PROV_RSA_AES supports the SHA 2 hash algorithms for signature validation not signa ture creation This provider type is recommended in order to validate signatures if no PKCS 11 device is available Optionally when using an advanced certificate the pin code can be passed as an additional semi column separated parameter This does not work with qualified certificates because they always require the pin code to be entered manually and every time If the name of the provider is omitted the default provider is used Examples 123456 being the pin code Provider Microsoft Base Cryptographic Provider v1 0 123456 Provider 123456
89. ovides the following advantages 1 By means of this service the tokens can be hosted centrally and used by any client computer which has access to the service 2 Cryptographic devices that can be used on Windows only can be made accessible to siging processes run ning on Non Windows systems 3 Cryptographic devices can be made accessible to processes running in non interactive sessions Many cryp tographic devices must always be used in an interactive session for two reasons First the middleware re quires the user to enter the pin interactively to create a qualified electronic signature Second USB tokens and smart cards are managed by Windows such that the device is available only to the user currently using the computer s console Therefore services remotely logged in users and applications running in locked sessions have no access to the device Note that this is a separate product and this chapter describes its usage with the 3 Heights PDF Security API only For more information on the 3 Heights Signature Creation and Validation Service and installation instructions please refer to its separate user manual Configuration Provider Property Provider The provider configuration string has the following syntax http server mydomain com lt port gt lt token gt lt password gt Where server mydomain com is the hostname of the server lt port gt is optional port of the server lt token gt the ID of the token
90. ping see the section Stamping PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 54 71 AddTimeStampSignature Method Boolean AddTimeStampSignature PdfSignature pSignature Add a document level Time stamp No appearance is created The following signature properties must be set TimeStampURL The following signature properties may be set Provider TimeStampCredentials ProxyURL ProxyCredentials BeginSession Method Boolean BeginSession String Provider The methods BeginSession and EndSession support bulk digital signing by keeping the session to the security device HSM Token or Cryptographic Provider open See the chapter Guidelines for Mass Signing for more guidelines For backwards compatibility the use of these methods is optional If used the Provider property may not be set If omitted an individual session to the provider indicated by the property Provider is used for each signature operation Parameters Provider See property Provider Return value True Session started successfully False Otherwise Close Method Boolean Close Close an opened input file If the document is already closed the method does nothing Return value True The file was closed successfully False Otherwise ErrorCode Property TPDFErrorCode ErrorCode Accessors Get This property can be accessed to receive the latest error
91. present The signature does not conform to the PAdES standard e g because the signature is not DER encoded or the CMS contains more than one SignerInfo An enumeration for permission flags If a flag is set the permission is granted ePermNoEncryption ePermA11 ePermPrint ePermModify ePermCopy ePermAnnotate ePermFillForms ePermSupportDisabilities ePermAssemble ePermDigitalPrint Do not apply encryption This enumeration shall not be combined with another enumeration When using this enumeration set both passwords to an empty string or null Grant all Permissions Low resolution printing Changing the document Content copying or extraction Annotations Filling of form fields Support for disabilities Document Assembly High resolution printing Changing permissions or granting multiple permissions is done using a bitwise or operator Changing the cur rent permissions in Visual Basic should be done like this Allow Printing Prohibit Printing Permission Permission Or ePermPrint Permission Permission And Not ePermPrint 11 Adobe Acrobat XI classifies such signatures as valid PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 72 71 7 Licensing and Copyright The 3 Heights PDF Security API is copyrighted This user s manual is also copyright protected it may be copied and given away provided that it remains unchanged including the copyright notice 8
92. r stamp rotation angles that are a multiple of 90 see rotate attribute x or y is ignored if respective align is used Example 1 relativepos 10 10 places stamp in upper left corner of page Example 2 relativepos 10 10 places stamp in upper right corner of page Example 3 relativepos 10 10 places stamp in lower left corner of page Example 4 relativepos 10 10 places stamp in lower right corner of page align center middle Align the stamp with the page center position horizontally at center of page the x value of relativepos is ignored and should be set to 0 middle position vertically at middle of page the y value of relativepos is ignored Example 1 position 0 4 align center centers the stamp horizontally and 4pt away from the bottom of the page Example 2 position 4 0 align middle centers the stamp vertically and 4pt away from the right edge of the page size w h The width and height of the stamp The stamp s content will be clipped to this rectangle If this is not specified or either w or h are zero the respective size is calculated to fit content PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 48 71 rotate r scale relToA4 autoorientation true alpha t type type ps rotate angle n origin x y ps translate offset x y ps transform matrixabcdxy Rotation of the stamp in degrees clockwise Scale the stamp relative to the page size i e make
93. ransparency Therefore for PDF A 1 conforming input files you must not set alpha to a value other than 1 0 Add Stroked Rectangle See fillrectangle Set the linewidth in points e g 1 0 The stroke color of the rectangle The color as RGB value where all values must be from 0 to 1 See fillrectangle il O PDF Tools AG Premium PDF Technology All coordinate and size values are in PDF units of 1 72 inch A4 595 x 842 points letter 612 x 792 points The origin of the coordinate system is generally the lower left corner of the reference object For stamps the reference object is the page for content operators the reference is the stamp rectangle Setting the name attribute of a stamp allows the stamp s content to be replaced later If an existing stamp with the same name exists in the input file its content is replaced Otherwise a new stamp is created Note that when updating a stamp its position and size remains Therefore if you intend to update a stamp make sure to create it using a size that is sufficiently large Attribute fontencoding The PDF A standard demands that all used fonts must be embedded in the PDF Since fonts with many glyphs can be very large in size gt 20MB unused glyphs are removed prior to embed ding This process is called subsetting The attribute fontencoding controls the subsetting Unicode Only the glyphs used by the stamp are embedded If the stamp is modified a new font that includes
94. res of the 3 Heights PDF Security API require fonts to be installed e g when stamping text The location of the font directories depends on the operating system Windows SystemRoot Fonts and directory Fonts which must be a direct sub directory of where the main DLL or executable resides Mac System Library Fonts and Library Fonts Unix PDFFONTDIR or usr 1ib X11 fonts Typel The fonts of the font directories and their properties are cached in a font cache located in the files font database in the temporary files folder The cache files have to be removed manually if fonts are added or removed from these directories The directory for temporary files is determined as follows The product checks for the existence of environment variables in the following order and uses the first path found Windows 1 The path specified by the TMP environment variable PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 25 71 2 The path specified by the TEMP environment variable 3 The path specified by the USERPROFILE environment variable 4 The Windows directory Unix The path specified by the PDFTMPDIR environment variable al 2 The path specified by the TMP environment variable 3 The tmp directory Example Command to remove the font cache files on Windows del TMP font database 5 5 Cryptographic Provider In order to use the 3 Heights PDF Security API
95. s Soft certificate files cannot be used directly Instead they must be imported into the certificate store of a cryptographic provider All Platforms The recommended way of using soft certificates is to import them into a store that offers a PKCS 11 interface and use the PKCS 11 Provider For example AHSM OpenCryptoki on Linux PKCS 11 softtoken on Solaris For more information and installation instructions of the above stores see separate document TechNotePKCS11 pdf Windows If no PKCS 11 provider is available soft certificates can be imported into Windows certificate store which can then be used as cryptographic provider Microsoft CryptoAPI Signature Service Signature services are a convenient alternative to storing certificates and key material locally The 3 Heights PDF Security API can use various different services whose configuration is explained in the fol lowing sections of this documentation 3 Heights Signature Creation and Validation Service SwissSign Personal Signing Service SwissSign SuisselD Signing Service QuoVadis sealsign 1See the description of the 3 Heights Signature Creation and Validation Service for more details on this topic PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 26 71 Swisscom All in Signing Service Custom Signature Handler If you want to create the cryptographic part of the signature yourself i e you want to implement th
96. s bin sample PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 13 71 NET Interface The 3 Heights PDF Security API does not provide a pure NET solution Instead it consists of NET assemblies which are added to the project and a native DLL which is called by the NET assemblies This has to be accounted for when installing and deploying the tool The NET assemblies NET d are to be added as references to the project They are required at compilation time See also chapter Getting Started PdfSecureAPl dil is not a NET assembly but a native DLL It is not to be added as a reference in the project The native DLL PafSecureAPI dll is called by the NET assembly PdfSecureNET dlll PdfsecureAPI dll must be found at execution time by the Windows operating system The common way to do this is adding PdfSecureAPI dll as an existing item to the project and set its property Copy to output directory to Copy if newer Alternatively the directory where PafSecureAPI dll resides can be added to the environment variable PATH or it can simply be copied manually to the output directory C Interface The header file pafsecureapi_c h needs to be included in the C C program The library PdfSecureAPi lib needs to be linked to the project The dynamic link library PdfSecureAP dll needs to be in path of executables e g on the environment variable PATH 2
97. s cryptographic functions such as creating or validating digital signatures a cryptographic provider is required The cryptographic provider manages certificates their private keys and implements cryptographic algorithms The 3 Heights PDF Security API can use various different cryptographic providers The following list shows for which type of signing certificate which provider can be used USB Token or Smart Card These devices typically offer a PKCS 11 interface which is the recommended way to use the certificate gt PKCS 11 Provider On Windows the certificate is usually also available in the Microsoft CryptoAPI This provider is not rec ommended unless you experience problems with your device s PKCS 11 interface If you need to sign documents on a non Windows system with an USB token that does not come with middleware for your platform you can use the 3 Heights Signature Creation and Validation Service If you need to sign documents on Windows in a non interactive or locked session use the 3 Heights Signature Creation and Validation Service Hardware Security Module HSM HSMs always offer very good PKCS 11 support gt PKCS 11 Provider For more information and installation instructions see separate document TechNotePKCS11 pdf Soft Certificate Soft certificates are typically PKCS 12 files that have the extension pfx or p12 and contain the signing certificate as well as the private key and trust chain issuer certificate
98. s for connection to proxy basic authorization host Hostname of proxy port Port for connection to proxy For SSL connections e g to a signature service the proxy must allow the HTTP CONNECT request to the signa ture service Example Configuration of a proxy server that is called myproxy and accepts HTTP connections on port 8080 doc SetSessionPropertyString Proxy http myproxy 8080 6The sizes of the TSP responses are cached only Cached TSP responses cannot be embedded but used for the computation of the signature length only PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 41 71 Configuration of Proxy Server and Firewall For the application of a Time stamp or online verification of certificates the signature software requires ac cess to the server of the certificates issuer e g http ocsp quovadisglobal com or http platinum qualified g2 ocsp swisssign net via HTTP The URL for verification is stored in the certificate the URL for Time stamp services is provided by the issuer In case these functions are not configured no access is required In organizations where a web proxy is in used it must be ensured that the required MIME types are supported These are OCSP application ocsp request application ocsp response Time stamp application timestamp query application timestamp reply Signature services Signature service specific MI
99. s is the field called Serial number in the certificate s Details tab 3 Certificate Name and optionally Issuer Properties Name and Issuer Common Name of the certificate e g PDF Tools AG in Windows certificate store this is called Issued To Optional Certificate Issuer e g QV Schweiz CA in Windows certificate store this is called Issued By Using PKCS 11 stores with missing issuer certificates Some PKCS 11 devices contain the signing certificate only However in order to embed revocation information it is important that the issuer certificates i e the whole trust chain is available as well On Windows missing issuer certificates can be loaded from the Windows certificate store So the missing certificates can be installed as follows 1 Get the certificates of the trust chain You can download them from the website of your certificate provider or do the following a Sign a document and open the output in Adobe Acrobat b Goto Signature Properties and then view the signer s certificate c Select a certificate of the trust chain d Export the certificate as Certificate File extension cer e Do this for all certificates of the trust chain 2 Open the exported files by double clicking on them in the Windows Explorer 3 Click button Install Certificate 4 Select automatically select the certificate store based on the type of certificate and finish imp
100. s not found at execution time This normally manifests when the constructor is called for the first time and exception is thrown normally of type System TypelnitializationException To resolve that ensure the native DLL is found at execution time For this see section NET Interface in the chapter Installation or the following FAQ https www pdf tools com pdf Support FAQ Article aspx name Exception type initializer 5 User s Guide 5 1 Overview of the API What is the 3 Heights PDF Security API about The 3 Heights PDF Security API provides three key functionalities related to security in PDF documents 1 Deal with encryption decryption and access permissions of PDF documents 2 Deal with digital signatures 3 Apply stamps to PDF documents These three functionalities can be combined they however are not closely related What encryption and what a digital signature is is described in the upcoming chapters O PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 22 71 5 2 How does the API work in general The 3 Heights PDF Security API requires a PDF document as input In this manual that document is referred to as input document In the graphic below that s the document on the left hand side The document can be opened from file or from memory If the document is encrypted it is in a first step decrypted Customer Application 3 Heights PDF Security Tool Decrypt User pwd
101. stamp half as large on a A5 and twice as large on a A3 page as specified Detect orientation portrait and landscape of page automatically and treat landscape page as 90 rotated portrait Useful to apply stamps to long or short edge of page The opacity of the stamp as a whole 1 0 for fully opaque 0 0 for fully transparent Default 1 0 The PDF A 1 standard does not allow transparency Therefore for PDF A 1 conforming input files you must not set alpha to a value other than 1 0 The type of the stamp annotation default The stamp is added to the page as a stamp annotation Creating or modifying stamps of this type will not invalidate existing signatures of the input document While it is not easily possible to remove stamps of this type it is possible to print a document without annotations foreground The stamp is added to the foreground of the page content Creating or modifying stamps of this type will invalidate all existing signatures of the input document It is not easily possible to remove stamps of this type nor can the document be printed without them background The stamp is added to the background of the page content Creating or modifying stamps of this type will invalidate all existing signatures of the input document It is not easily possible to remove stamps of this type nor can the document be printed without them Note that stamps placed this way can be hidden when pages contain a non transparen
102. string crypt filter e g both must be RC4 or AES Other tools such as the 3 Heights PDF tools do not have this limitation Setting this value to an empty string or null means the default filter is used Return value True The opened document could successfully be saved to file Check the property ErrorCode after SaveAs to identify possible non critical issues during the process These are SIG_CREA_E_OCSP Couldn t get response from OCSP server SIG_CREA_E_CRL Couldn t get response from CRL server SIG_CREA_E_TSP Couldn t get response from Time stamp server a False Otherwise One of the following occurred The output file cannot be created SIG_CREA_E_SESSION Cannot create a session or CSP SIG_CREA_E STORE The certificate store is not available SIG_CREA_E_CERT The certificate cannot be found SIG_CREA_E_PRIVKEY The private key is not available SIG_CREA_E_INVCERT The signing certificate is invalid because it has expired is not yet valid or was revoked PDF_E_SIGLENGTH Incorrect signature length Set permission flags equally to Acrobat 7 In Acrobat 7 there are four different fields check boxes that can be set In brackets are the corresponding permission flags This is a complete list all other values can be ignored 10This is not a complete list If SaveAs returs False it is recommended to abort the processing of the file
103. t If multiple problems are detected the error code with the highest priority is returned False The signature is corrupt or the document has been modified See also Enumeration TPDFErrorCode 6 2 PdfSignature Interface This interface allows creating a signature and setting its position and appearance The visual part of the sig nature consists of two multi line texts The string of both texts are generated automatically based on the signature properties if not set manually Contactinfo Property String ContactInfo Accessors Get Set Default cii Add a descriptive text as signer contact info e g a phone number This enables a recipient to contact the signer to verify the signature This is not required in order to create a valid signature If this property is set to an empty string no entry is created PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 62 71 Date Property String Date Accessors Get Set Default D 00000000000000Z set to current date when signature is added This is the date when the signature is added When this property is not set the current time and date is used The format of the date is D YYYYMMDDHHMMSSZ The meanings are D Header of Date Format YYYY year MM month DD day HH hour MM minutes ss seconds Z UTC Zulu Time Example for December 17 2007 14 15 13 GMT D 20071217141513Z Note This property is set
104. t background In these cases you may rather want to put the stamps in the foreground but apply alpha transparency to achieve a result with existing content not covered completely Rotate Applies to stamp content defined within this tag Rotate by n degrees counter clockwise e g 90 Set the origin of the rotation in points e g 100 100 Coordinate Translation Applies to stamp content defined within this tag The x horizontal and y vertical offset in points A translation by x y is equal to a transformation by1001xy Coordinate Transformation Applies to stamp content defined within this tag The transformation matrix to scale rotate skew translate etc the stamp e g Identity 100100 Scale by factor 2 200200 Translate 50 points left 200 up 1001 50 200 Rotate by x cos x sin x sin x cos x O O For 90 7 2 that is 0 1 1000 7Up to version 4 5 6 0 of the 3 Heights PDF Security API this type was called content PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 49 71 ps filltext color r g b position x y align xalign yalign font name size n fontencoding encoding text text ps stroketext linewidth f color r g b position x y align xalign yalign font name size n fontencoding encoding text text Add Filled Text The color as RGB value where all values must be from 0 to 1 e g Red 100 Green 010 Black 000 Gray 0 5 0 5 0 5 T
105. tStr Accessors Get Set The hex string representation of the signer certificate s shal fingerprint This property can be used to select the signer certificate for signing see description of Cryptographic Provider in use All characters outside the ranges 0 9 a f and A F are ignored In the Microsoft Management Console the Thumbprint value can be used without conversion if the Thumbprint algorithm is sha1 E g b5 e4 5c 98 5a 7e 05 ff f4 c6 a3 45 13 48 Ob c6 9d e4 5d f5 Store Property String Store Accessors Get Set Default MY For the Microsoft CryptoAPI Provider this defines the certificate store from where the signing certificate should be taken This depends on the OS The default is MY Other supported values are CA or ROOT StoreLocation Property Integer StoreLocation Accessors Get Set Default 1 For the Microsoft CryptoAPI Provider this defines the location of the certificate store from where the signing certificate should be taken Supported are o Local Machine 1 Current User default For more information see the detailed description of the Microsoft CryptoAPI Provider O PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 68 71 StrokeColor Property Long StrokeColor Accessors Get Set Default 8405056 red 64 green 64 blue 128 This is the color of the signature s border line
106. te 90 scale relToA4 autoorientation true alpha 0 75 type foreground gt lt ps fillrectangle color 0 8 0 8 0 8 gt lt ps strokerectangle gt lt ps filltext align center middle font Arial size 8 text stamp on long endge gt lt ps stamp gt lt ps pdfstamp gt 6 Reference Manual Note this manual describes the COM interface only Other interfaces C Java NET however work similarly i e they have calls with similar names and the call sequence to be used is the same as with COM 6 1 PdfSecure Interface AddDocMDP Signature Method Boolean AddDocMDPSignature PdfSignature pSignature Short accessPermissions Add a document MDP modification detection and prevention signature A PDF document can at most con tain one MDP signature A DocMDP signature defines the access permissions of the document It should be combined with standard encryption i e the function SaveAs should not apply encryption PDF documents with DocMDP signatures added with the 3 Heights PDF Security API require Acrobat 7 or later to be opened Parameters pSignature The digital signature that is to be added The properties of the signature must be set before it is added accessPermissions The access permissions granted are one of the following three values 1 No changes to the document are permitted any change to the document invalidates the signature 2 Permitted changes are filling in forms instantia
107. ting page templates and signing other changes invalidate the signature 3 Permitted changes are the same as for 2 as well as annotation creation deletion and modification other changes invalidate the signature Return value True Successfully added the signature to the document Note At this point it is not verified whether the certificate is valid or not If an invalid certificate is provided the SaveAs function will fail later on False Otherwise Note This version can create visible DocMDP signatures In order to create an invisible signature set the signature s rectangle to 0 0 O 0 PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 53 71 AddPreparedSignature Method Boolean AddPreparedSignature PdfSignature pSignature Add a signature field including an appearance but without a digital signature This method must be called prior to SaveAs or SavelnMemory and should only be used in combination with SignPreparedSignature Parameters pSignature The digital signature from which the field and appearance is created The properties of the signature must be set before it is added Return value True Successfully prepared signature False Otherwise AddSignature Method Boolean AddSignature PdfSignature pSignature Add a digital signature to the document The signature is defined using a PdfSignature object This method must be called pri
108. to un initialize use PdfSecureUnInitialize Other than that equal call sequences as in the COM interface can be used include lt stdio h gt include pdfsecureapi_c h include pdfsecuritydecl h int main int argc char argv TPdfSecure pPdfSecure PdfSecurelnitialize pPdfSecure PdfSecureCreateObject PdfSecureOpen pPdfSecure argv i PdfSecureSaveAsA pPdfSecure argvl2 PdfSecureClose pPdfSecure PdfSecureDestroy0bject pPdfSecure PDF Tools AG Premium PDF Technology Drool caba A DO VU PDF Security API Version 4 5 August 26 2015 19 71 PdfSecureUnInitialize return 0 4 3 NET As opposed to previous versions the Windows build numbers 1 7 1 and later provide a NET interface There should be at least one NET sample for MS Visual Studio 2005 available in the ZIP archive of the Windows Version of the 3 Heights PDF Security API The easiest for a quick start is to refer to this sample In order to create a new project from scratch do the following steps 1 Start Visual Studio and create a new C or VB project 2 Add a reference to the NET assemblies To do so in the Solution Explorer right click your project and select Add Reference The Add Reference dialog will appear In the tab Browse browse for the NET 3 assemblies ibpdfNET dll and PdfsecureNET dll Add them to the project as shown below CI 2x NET
109. uction 1 1 Description The 3 Heights PDF Security API enables the application of digital signatures to PDF documents and their sub sequent protection through setting passwords and user authorizations Both standard signatures and qualified signatures that use signature cards smart cards USB tokens HSM can be used PDF documents used in professional circumstances contain important information that needs to be protected against misuse and unintentional alteration This is achieved by protecting PDF documents through encryption and user authorization rights PDF Security Tool a A Verify Signature Decrypt je DJ a o0 A 0 un Certificate US de Time Server OCSP Server Parameters When exchanging electronic documents the ability to ascertain that a document is authentic and has not been manipulated on its way from sender to recipient is of particular importance This is only achievable through the use of electronic signatures Through its interfaces C Java NET COM and thanks to its flexibility a developer can integrate the 3 Heights PDF Security API in virtually any application O PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 3 71 1 2 Functions The 3 Heights PDF Security API enables users to encrypt and if the passwords are known decrypt PDF documents The tool can set and cancel all known PDF user authorizations
110. word The standard security handler allows access permissions and up to two passwords to be specified for a docu ment An owner password and a user password The user password protects the document against unauthorized opening and reading If a PDF document is protected by a user password either the user or owner password must be provided to open and read the document If a document has a user password it must have an owner password as well If no owner password is defined the owner password is the same as the user password The owner password is also referred to as the author s password This password grants full access to the doc ument Not only can the document be opened and read it also allows for changing the document s security settings access permission and passwords The following table shows the four possible combinations of passwords and how an application processing such a PDF document behaves Table Owner and User Passwords Userrwd OwnerPwd Behavior none none Everyone can read Everyone can change security settings No encryption none set Everyone can read The user password is an empty string Owner password re quired to change security settings set none User password required to read The owner password is equal to the user pass word User password required to change security settings set set User or owner password required to read Owner password required to change security settings Permission Flags
111. y as byte array using the method SetSessionPropertyBytes Name Type Required Value DSSProfile String required http ais swisscom ch 1 0 SSLClientCertificate File required SSL client certificate in PKCS 12 Format p12 pfx File must contain the certificate itself all certifi cates of the trust chain and the private key SY Mel Tee EEAO String optional Password to decrypt the private key of the SLL client certificate SSLServerCertificate File recommended Certificate of the server or its issuer CA certifi cate in DER Format der cer Note If this property is not set the server cer tificate is not verified at all Identity String required The identity string as provided by Swisscom lt customer name gt lt key identity gt RequestID String recommended Any string that can be used to track the re quest Example An UUID like AE57F021 COEB 4AE0 8E5E 67FB93E5BC7F 5This parameter is not used for certificate selection but for the signature appearance and signature description in the PDF only O PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 36 71 On Demand Certificates To request an on demand certificate the following additional property has to be set Type Required Value MEAN EDINE String required The requested distinguished name Example cn Hans Muster o ACME c CH Step Up Authorization using Mobile ID To use the step up authorization the following addit
112. y handler e g for a proprietary digital rights management DRM system The file contains unrendered XFA form fields i e the file is an XFA and not a PDF file Aborted processing of signed and encrypted document Cannot create a session or CSP Cannot open certificate store Certificate not found in store The signing certificate is invalid Couldn t get response from OCSP server Couldn t get response from CRL server Couldn t get response from Time stamp server Private key not available This is usually because a pin is required and was not entered correctly Server error The cryptographic provider does not implement a require algorithm Another failure occurred Incorrect signature length PDF Tools AG Premium PDF Technology PDF Security API Version 4 5 August 26 2015 71 71 SIG_VAL_E_ALGO SIG_VAL_E_FAILURE SIG_VAL_E_CMS SIG_VAL_E_DIGEST SIG_VAL_E_SIGNER CERT SIG_VAL_E_SIGNATURE SIG_VAL_W_ISSUER CERT SIG_VAL_W_NOTRUST CHAIN SIG_VAL_W_TSP SIG_VAL_W_TSPCERT SIG_VAL_W_NOTSP SIG_VAL_W_PADES TPDFPermission Unsupported algorithm found Program failure occurred Malformed cryptographic message syntax CMS Digest mismatch document has been modified Signer s certificate is missing Signature is not valid None of the certificates was found in the store The trust chain is not embedded The Time stamp is invalid The Time stamp certificate was not found in the store The Time stamp is not

3-Heights™ PDF Security API, User Manual

Contents

Download Pdf Manuals

Related Search

Related Contents

3-Heights&trade; PDF Security API, User Manual

Contents

Download Pdf Manuals

Related Search

Related Contents

3-Heights™ PDF Security API, User Manual