Web API for PDF processing

Introduction

New development challenges continuously call for yet another things to be done to circumvent the tricky limitations all big name platform providers impose on us for whatever reasons. Nevertheless we, at Apitron, believe that it just makes our software better and if one could use a rewording – cuts it like a diamond for it to become an even better all-around tool for our customers.

We already went a long way to make our tools cross-platform with .NET, MONO and Xamarin, so now they cover many usage scenarios and provide a solid toolset for creating full-cycle PDF processing apps. But we have even more to offer, a web API for PDF processing with the focus on signing and watermarking of documents. It’s designed to be hosted in-house but we have a demo installation publicly available as well.

Demo

Like it has been said before, the API can be hosted anywhere including your own server if you need. It supports signing and watermarking of PDF documents and we have set up a test installation for you to try it out. The slides below demonstrate the user interface of a test client web app that makes use of the aforementioned web api and is available for download from our github repo. As the first step after downloading, you’d have to configure the app to use the right web api installation URL by editing the “ServiceUrl” in its web.config. We used our demo url here.

Pic. 1 Configuring client app

After that we can run the app in browser and proceed by selecting the file and desired action, see below:

Pic. 2 Selecting source file and desired action

Source document used here is a dummy letter crafted for illustrative purposes, it’s shown below:

Pic. 3 Source PDF document

After setting up the desired signature properties as shown on the next slide, we will get our doc sent to the server, signed there and downloaded back. The demo installation uses https, so there won’t a be a plaintext data exchange happening and we won’t store and use any data sent to our web api except for providing you with signing and watermarking services.

Pic. 4 Applying signature settings

So here we can choose among the existing server keys for signing but the demo installation has only one such key listed (with a word “password” used as its actual password). You can also upload your own key and sign with it if you wish. The purpose of having a set of pre-loaded keys is to provide an organization with a way to share certain functions among employees without actually giving them access to the signing certificates and having common keys in one place for easy management and better protection. 

It might be the case that you’d want to employ a HSM or other means for storing the keys. All these things become possible with a custom setup and implementation of storage modules. Contact us if you are interested to know more. Our web API is based on Apitron PDF Kit product and requires a license for this product to become fully functional. Otherwise it will work in evaluation mode, but the important note is that web API package itself is provided free of charge.

The results of the signing operation are shown below, signature image (if set) takes priority over signature text hence the name and surname represented by the supplied image at the bottom of the page.

Pic. 5 Signed PDF document

Watermarking requires less parameters for now, it can be either a text string or an image as shown below:

Pic. 6 Applying watermark settings

The image (if set) gets centered on the page and the text gets aligned diagonally along the line coming from the left bottom corner to the top right corner.

Sample watermarked document is shown below:

Pic. 7 Watermarked PDF document

The Code

JS code sample showing how to perform the request to the API is provided below, it is the excerpt from the client app referenced in this post, so you can examine its code and find more info there.

[Javascript]
...
var formData = new FormData();
formData.append("signatureText", “your text here”);
formData.append("signatureImage", [image data here]);
formData.append("signingKeyName", “key name here”);
formData.append("signingCertificate", [cert data here]);
formData.append("signingPassword", “cert password here”);
formData.append("signatureBoundary", “115,150,185,190”);
formData.append("signaturePageIndexStart", 0);
formData.append("signaturePageIndexEnd", 0);
$.each(filesToSend,
function (index, value) {
formData.append("sourceFiles" + index, value);
});

// call signing api
$.ajax({ url: “signing api url here”, 
        data: formData, 
        contentType: false, 
        processData: false, 
        type: 'POST',
        success: function (data) {
        getResults(“signing api url here”, data);
        },
        error: function (xhr, textStatus, errorThrown) {
        reportError("Error occured while contacting the server: " + textStatus);
    }
});

We’re performing the REST call here, namely POST the form with parameters describing our signing request, get back the signing task Id and later query the same service using the acquired task Id to get the result. We recommend looking at the sources of the sample app for the detailed explanation on how to make these calls.

Summary

We hope that new web API will facilitate the development of your PDF processing apps. It’s never been so easy to handle PDFs just with a few lines of code and get the serious job done so quickly. An option to have your own installation of the web api free of charge is a great benefit and our professional customer support can always help you with any questions you might have.

PDF 2.0 specification overview

As you probably know the PDF 2.0 specification has been recently released and it introduced many long awaited features as well as deprecated some stuff. Here we would like to highlight the changes, so you could have an overview of what is going to happen in PDF world soon. Our dev team is working on adding support for all the new features and some of them are already implemented, but nevertheless it will take some time to align the products with the new spec.

So here are the features:

• "Unencrypted wrapper document" – the way to use custom encryption algorithms for encrypting string and streams
• "Use of black point compensation" – related to rendering intents and color conversion using ICC
• "Projection annotations" – projection annotations provide a way to save 3D and other specialized measurements and comments as markup annotations. These measurements and comments then persist in the document
• "CAdES signatures as used in PDF" – adds new subfilter to PDF signatures
• "Long term validation of signatures" along with the "Document Security Store (DSS)" and "Document timestamp (DTS) dictionary" specifies the way to store the information needed to validate signatures on a long-term basis (CRL, OCSP and Timestamp data)
• "Geospatial features" – new way to store geospatial data
• "Rich media" annotations – common framework for video, audio and animated content
• "Namespaces" for tagged PDF – new way for preserving logical structure of docs converted from other formats
• "Pronunciation hints" – a way to aid text-to-speech processors with correct pronunciation
• "Document parts" – specifies the way the to divide the document into logical parts with different purposes, simply speaking, defining subdocuments
• "Associated files" – a way to indicate the relationship between the PDF objects in the document and content in other formats
• Support for ISO 14739-1:2014 Product Representation Compact (PRC) file format
• Support for UTF-8

Existing PDF features were updated by adding the following capabilities:

• Transparency and blend mode attributes for the annotations
• Stamp Annot intent
• Polygon and Polyline real paths
• 256-bit AES encryption
• ECC-based certificates
• Unicode based passwords
• Document requirement extensions
• New value for tab order of fields and annotations
• Page-level OutputIntents
• Referenced (external) OutputIntents
• Thumbnails for embedded files
• Halftone Origin (HTO)
• Measurement and Point Data for image and form XObjects
• L (length) key for inline image data
• Viewer preferences enforcement (for print scaling)
• 3D measurements
• GoToDp action
• RichMediaExecute action
• Extension for GoTo and GoToR supporting linking to specific structure elements
• Extension for Signature Field Locks and Signature Seed Values
• Extensions for 3D viewing conditions, including transparency
• Ref (reference) structure elements
• PageNum and Bates artifact types
• New list types for structured lists
• “Short” (short name) attribute for table header cells
• Extensions to OutputIntents (MixingHints and SpectralData)

And of course, many things were deprecated, see the list below:

• XFA (finally!) including NeedsRendering
• Movie, Sound and TrapNet annotations
• Movie and Sound actions
• Info dictionary
• Assistive technology restrictions via DRM
• ProcSet
• Operation system specific file specifications
• Operation system specific additions to Launch actions
• Names for XObjects
• Names for Fonts
• Arrays of Blend Modes
• Alternate Presentations
• Open prepress interface
• CharSet (For Type 1 fonts)
• CIDSet (for CID fonts)
• Prepress viewer preferences (ViewArea, ViewClip and so on)
• NeedAppearances
• adbe.pkcs7.sha1 subfilter, as SHA1 was considered weak
• adbe.x509.rsa_sha1 subfilter, same as above
• Encryption of FDF files
• Suspects flag in MarkInfo dictionary
• UR signatures

If we missed something just let us know and we’ll add it asap. New releases will be available soon, so keep an eye on Apitron PDF Kit and Apitron PDF Rasterizer pages and nuget packages.

Government issued smart cards and PDF documents signing

Many EU and non-EU governments and organizations are now issuing so-called e-legitimations, e.g. SuisseID / MobileID in Switzerland, BankID / MobileID / National ID in Nordic countries, ID cards in Italy and Germany, Dutch copy of BankID called iDin, Belgian National ID and so on. Some of them are produced in the form of smartcards carrying necessary digital certificates which can be used for documents signing. 

There are a few ways to work with these cards from the development perspective and it depends on the provided driver and, consequently, supported interfaces. If the target OS is Windows you can either use CryptoAPI, CNG (CryptoAPI Next Generation) or PKCS#11 if supported by the device. Most vendors supply drivers for both, so it shouldn't be the problem. In case of .NET there is a great wrapper for PKCS#11 called Pkcs11Interop that is compliant with v.2.20 of the specification. Working with CryptoAPI often requires PInvokes to be defined and mastered and, honestly, may become quite challenging task.

With macOS it's a bit foggy, nevertheless you can use tokend drivers provided by various vendors either open source or commercial. Apple's own signing API works for this purpose however it may require dancing around to get things working.

Whichever way you choose, we can provide you with a reliable PDF processing library so you'd be able to sign documents without any problems, once you try our API defined to handle various signing scenarios. Apitron PDF Kit sets high standards in PDF processing and our team is well known for the outstanding customer support. Please don't hesitate to contact us if you have any questions, we'll be happy to help you.

Apitron PDF Kit Extensions Update: Text Watermarks

Introduction

 

In our previous post we announced the release of the open source extensions library for Apitron PDF Kit. We continue making code contributions to this project, so recently a pack of changes related to text watermark support was added and now you can promptly add watermarks using text strings in addition to images.

For those thinking about keeping doc’s size as small as possible, textual watermarks seem to have a clear advantage over images as they usually need less bytes to store. The source code for the library can be found in our github repo by the following link. See the demo of new functionality and samples below.

Code samples

Adding text watermark is super easy:

using (Stream inputStream = File.Open("../../data/letter_unsigned.pdf", FileMode.Open))
{
    string watermarkText = "TOP secret -for INTERNAL use - TOP secret - for

       INTERNAL use - TOP secret - for INTERNAL use - TOP secret";

    using (FixedDocument doc = new FixedDocument(inputStream))
    {
        doc.WatermarkText(watermarkText, outputFileName);
    }
}

The result is below:

 

Pic.1 Text watermark

Summary

By releasing the Apitron PDF Kit Extensions we wanted to show you how to use the base API and at the same time make things simpler by implementing some tricky things in very a customizable way. Just get the base code and adapt it to your needs or add you own extensions. Don’t forget to share nice snippets with others.

Open source Apitron PDF Kit extensions library

Introduction

Apitron PDF Kit is an outstanding library for all kinds of tasks related to PDF, it offers well-designed and balanced API that follows the specification as much as possible at the same time making your life easier by automating many routine operations. 

We decided to take it one step further and introduced Apitron PDF Kit open source extensions library which would automate most frequent pdf manipulation activities, and started with adding digital signatures and watermarks. 

The project pursues two main goals:

1. Make PDF processing more intuitive and straightforward

2. Show how the base Apitron PDF Kit API works using real-life examples

The source code for the library can be found in our github repo by the following link. We will probably wrap it as a nuget package later, but for now you can just checkout the code and compile it yourself.

Code samples

Signing is very simple and consist of a one line call of the method Sign, you provide the certicate, password, signature image and its boundaries and a few optional params if needed.

using (Stream inputStream = File.Open("../../data/letter_unsigned.pdf", FileMode.Open))
{
     using (FixedDocument doc = new FixedDocument(inputStream))
     {
         doc.Sign("../../data/johndoe.pfx", "password",
                    "../../data/signatureImage.png",
         new Boundary(100, 140, 190, 180), outputFileName);
     }
}

And the result:

Pic. 1 Signed PDF Document

 

Same applies to stamping a document with a transparent watermark, just add a one-line call and voilà:

using (Stream inputStream = File.Open("../../data/letter_unsigned.pdf", FileMode.Open))
{
     using (FixedDocument doc = new FixedDocument(inputStream))
     {
         doc.Watermark("../../data/watermarkTransparent.png", outputFileName);
     }
}


The result is below:

Pic. 2 Stamped PDF document

 

Summary

If you need to incorporate the basic PDF processing functionality into your applications, then the open-source Apitron PDF Kit extensions library we’ve published a few weeks ago could be the right choice. It saves time keeping things simple, and you can always fallback to the main API if you need something going beyond its capabilities. 

Please let us know what you think about it or suggest new functions to implement. If you want your code to be added to the library just send us a patch for review.

Signing pdf documents with smartcards using cryptoapi or PKCS#11 cryptographic token interface

Signing with smartcards might be challenging as they usually restrict private key export and only allow signing via own custom api, integrate with existing cryptoserviceproviders (windows cryptoapi) or provide an implementation of PKCS#11 cryptographic token interface.

If you need to implement an advanced signing workflow using smart cards, we can help you on the way as our products are fully compatible and provide extensible interfaces for these purposes. Should you have any questions, just let us know and we'll be happy to help you.

How to programmatically delete, edit or replace content in PDF documents

Introduction

Replacing, editing or deleting content from PDF documents programmatically is not a trivial task and requires expert knowledge of the format and internal structures to be implemented from scratch. Luckily, we made it much easier for you by introducing native support for these operations. You can examine document’s content page by page and change the things you need without any significant efforts. In this article we’ll demonstrate how to implement text and image replacement or editing, removing contents from the desired area or region, resources replacement, graphics paths alteration, and getting content elements’ boundaries.

Replacing text and images

Let’s assume you’re developing a web-based solution for a real estate agency and you need to process advertisements stored as PDF documents. One of them could look as below:

Pic. 1 Sample advertisement stored as PDF

But the complete listing should only be accessible to the logged in customers, while you still want the ad to be viewable by other users but with some restrictions that include price and the photo of the object. One of solutions is to generate it dynamically. Here is the code: 

static void Main(string[] args)

{

       ReplaceTextAndImages("../../../data/advertisement.pdf", "$","Price: contact us",

              "../../../data/replacement.png");

}

private static void ReplaceTextAndImages(string inputFilePath, string oldText, 

      string newText, string replacementImagePath)

{

    using (Stream inputStream = File.Open(inputFilePath, FileMode.Open, FileAccess.Read))

    {

        using (FixedDocument doc = new FixedDocument(inputStream))

        {

            // add the replacement image to document's resources

            doc.ResourceManager.RegisterResource(new Image("replacement_image",

                  replacementImagePath, true));

            // enumerate content elements found on document's first page

            foreach (IContentElement element in doc.Pages[0].Elements)

            {

                // handle the text element case

                if (element.ElementType == ElementType.Text)

                {

                    TextContentElement textElement = element as TextContentElement;

                    if (textElement != null)

                    {

                        // go thought all the text segments and replace 

                        // the segment that contains the sample text

                        foreach (TextSegment textSegment in textElement.Segments)

                        {

                            if (textSegment.Text.Contains(oldText))

                            {

                                TextObject newTextObject = 

                                new TextObject(textSegment.FontName,textSegment.FontSize);

                                newTextObject.AppendText(newText);

                                textSegment.ReplaceText(0, textSegment.Text.Length, newTextObject);

                            }

                        }

                    }

                } // handle image case

                else if (element.ElementType == ElementType.Image)

                {

                    ImageContentElement imageElement = element as ImageContentElement;

                    if (imageElement != null)

                    {

                        // just replace the image with new one using

                        // registered resource, removing old one

                        imageElement.Replace("replacement_image", true);

                    }

                }

            }

            // save modified file

            using (Stream outputStream = File.Create(outputFileName))

            {

                doc.Save(outputStream);

            }

        }

    }

    Process.Start(outputFileName);

} 

And the resulting file produced by this code is shown below:

Pic. 2 Edited PDF document

Content deletion

Let’s say you have a document shown below and would like to remove all content that intersects with an arbitrary rectangular region.

Pic. 3 Sample document for content removal

Here is the code that does the job, it also highlights the elements that were removed using their calculated boundaries:

static void Main(string[] args)

{

    RemoveContentInRect("../../../data/apitron_pdf_kit_in_action_excerpt.pdf",

          new Boundary(70, 200, 330, 450));

}

private static void RemoveContentInRect(string inputFilePath, Boundary redactionRect)

{

    using (Stream inputStream = File.Open(inputFilePath, FileMode.Open, FileAccess.Read))

    {

        using (FixedDocument doc = new FixedDocument(inputStream))

        {

            doc.ResourceManager.RegisterResource(

               new GraphicsState("myGraphicsState") {CurrentNonStrokingAlpha = 0.3});

            // enumerate content elements found on document's first page

            Page firstPage = doc.Pages[0];

            firstPage.Content.SaveGraphicsState();

            firstPage.Content.SetDeviceStrokingColor(new []{1.0,0,0});

            foreach (IContentElement element in firstPage.Elements)

            {

                // remove elements falling into the deletion region

                // even if they just overlap

                if (element.ElementType == ElementType.Text)

                {

                    TextContentElement textElement = (TextContentElement) element;

                    foreach (TextSegment segment in textElement.Segments)

                    {

                        if (RectsOverlap(redactionRect, segment.Boundary))

                        {

                            firstPage.Content.StrokePath(Path.CreateRect(segment.Boundary));

                            segment.Remove();

                        }

                    }

                }

                else if (!RectsOverlap(redactionRect, element.Boundary))

                {

                    firstPage.Content.StrokePath(Path.CreateRect(element.Boundary));

                    element.Remove();

                }

            }

                

            // highlight deletetion region

            firstPage.Content.SetGraphicsState("myGraphicsState");

            firstPage.Content.SetDeviceStrokingColor(new []{0.0});

            firstPage.Content.SetDeviceNonStrokingColor(new []{0.0});

            firstPage.Content.FillAndStrokePath(Path.CreateRect(redactionRect));

            firstPage.Content.RestoreGraphicsState();

            // save modified file

            using (Stream outputStream = File.Create(outputFileName))

            {

                doc.Save(outputStream);

            }

        }

    }

}

public static bool RectsOverlap(Boundary a, Boundary b)

{

    return (a.Left < b.Right && a.Right> b.Left && a.Bottom<b.Top && a.Top>b.Bottom);

}

Resulting document is demonstrated below:

Pic. 4 Document with partially removed content

Changing existing drawings or graphics paths

If you have a drawing you would like to alter there is an API for that as well. You can also prepend or append PDF content to it, scale, translate or delete. Here is our sample file:

Pic. 5 PDF document with vector drawing

And our code that changes it a bit by altering non stroking colors for all found paths:


static void Main(string[] args)
{
    ReplacePaths("../../../data/graphics.pdf");
}

private static void ReplacePaths(string inputFilePath)
{
    using (Stream inputStream = File.Open(inputFilePath, FileMode.Open, FileAccess.Read))
    {
        using (FixedDocument doc = new FixedDocument(inputStream))
        {
            double colorComponent = 0;
            double colorDelta = 0.1;

            // enumerate content elements found on document's first page
            foreach (IContentElement element in doc.Pages[0].Elements)
            {
                // change the fill color of each found drawing
                if (element.ElementType == ElementType.Drawing)
                {
                    DrawingContentElement drawingElement = (DrawingContentElement) element;
                    drawingElement.SetNonStrokingColor(
                          new double[] { Math.Min(colorComponent,1),0, 0});
                    colorComponent += colorDelta;
                }
            }

            // save modified file
            using (Stream outputStream = File.Create(outputFileName))
            {
                doc.Save(outputStream);
            }
        }
    }

    Process.Start(outputFileName);
}

You can set stroking or non-stroking colors, examine drawing rule or operation type used, even examine the path or add some content by using AddContent method if you need.

The resulting document produced by the code is shown below:

Pic. 6 Edited graphics paths

Replacing resources in PDF documents

You probably know that PDF documents can contains various resources like fonts, tiling patterns, images, FormXObjects, colorprofiles etc. Whenever you need to replace a resource you can use a special API created for that.

Every FixedDocument (our name for PDF document) has its own resource manager accessible by the property of the same name. So in order to change the resource you can use the following code (relevant part is highlighted):

static void Main(string[] args)

{

    using (Stream inputStream = File.Open("../../../data/patternFill.pdf",

         FileMode.Open, FileAccess.Read))

    {

        using (FixedDocument doc = new FixedDocument(inputStream))

        {

            // create a new tiling pattern

            TilingPattern pattern = new TilingPattern("myNewPattern", 

      new Boundary(0, 0, 20, 20), 25, 25);

            pattern.Content.SetDeviceNonStrokingColor(new double[] { 0.1, 0.5, 0.7 });

            pattern.Content.FillAndStrokePath(Path.CreateCircle(10, 10,9));

            // register new pattern as a resource

            doc.ResourceManager.RegisterResource(pattern);

            // replace the old pattern with new one

            doc.ResourceManager.RegisterReplacement("myPattern","myNewPattern");

            //save modified file

            using (Stream outputStream = File.Create(outputFileName))

            {

                doc.Save(outputStream);

            }

        }

    }

    Process.Start(outputFileName);

}

In this example we replaced the old tiling pattern resource with the new one. Using this technique you can change the appearance of the PDF documents just by changing resources used by drawing operations.

Summary

In this article we demonstrated a few possible scenarios for content editing, removal and replacement in PDF. The topic is quite extensive, so probably we didn’t cover your particular case or maybe you have a specific question. If you need any help with the API or a professional advice just drop us an email, and we’ll be happy to assist you. All samples used in this article can be found in our github repo as well.

Long-term validation of signatures in PDF documents or LTV enabled signatures

Introduction 

 

Long-term validation of signatures in PDF documents is a mechanism to check that the signature and all related certificates are still valid at the time of checking (opening the doc) without making any requests to the signing authorities. That is all required information including OCSP responses, CRLs and timestamp should be present into the document.

Checking long term validation state

So, how can you check if the file you're viewing has LTV enabled signatures? See the image below that demonstrates that:

 

 

Pic.1 LTV-enabled signature

Basically PDF reader makes the check for you and displays the "Signature is LTV enabled" message. It also says that the signature is timestamped and it's very important because it proves that the file was signed at specific time and the clock couldn't be manipulated to produce the signature. Another way to check if the signature is LTV enabled is by examining whether the certificates' revocation info is embedded into the document. To do this, open signature properties window and check certs from the certificate chain one by one, you should see the similar picture:

Pic.2 Checking certificate revocation info status

Additionally, you can take a look at advanced signature properties to find the timestamping authority details, hash algorithm used and producer info.

Pic.3 Advanced signature properties

Conclusion

 

While LTV can be tricky to implement sometimes, we have invaluable experience in that area and our products are ready to process LTV enabled documents as well.  So if you need any help with implementing digital signatures workflow, just let us know and we'll be happy to come up with a solution for you.