Skip to main content
Version: 1.3

Set up digital signing for Pdftools SDK

Depending on the type of digital signature you want to add to documents using the Pdftools SDK, you may need to:

Configuring HTTPS connections​

When the Pdftools SDK connects to a remote service using HTTPS (SSL/TLS) communication, the server certificate's trustworthiness is verified by the HttpClientHandler class. If the verification process fails, the connection to the server is aborted.

The verification process requires a trust store; otherwise, verification always fails. The system's default trust store is used. Additional trusted certificates may be added using the AddTrustedCertificate method of the HttpClientHandler class.

When an SSL/TLS connection requires a client certificate (for example, when connecting to an online signing service), the SetClientCertificate and SetClientCertificateAndKey methods of the HttpClientHandler class are used to set the client certificate and its private key.

The default trust store is configured in the following locations:

The Windows certificate store for Trusted Root Certification Authorities is used. You can install the root certificate of a private CA manually on a computer by using the CertMgr tool. The certificate store is only available if the user profile has been loaded.

note

If it is not possible to verify the server certificate, you can disable verification by setting the SslVerifyServerCertificate property of the HttpClientHandler to false.

However, this approach is strongly discouraged in any production environment.

Storing local certificates​

When signing PDF documents, additional certificates may be required. For example, you may need additional certificates when the OutputOptions class is configured to add all certificates of the signing certificate's trust chain to the output document security store (DSS) to enable long-term signature validation (LTV).

If the certificate provider allows certificates to be downloaded, the Pdftools SDK downloads the required certificates and stores them in a local Certificates directory. You may also manually add certificates to the Certificates directory.

The Pdftools SDK stores and searches for local certificates, in either PEM (.pem, ASCII text) or DER (.cer, binary) format, in the following locations:

%LOCALAPPDATA%\PDF Tools AG\Certificates

%ProgramData%\PDF Tools AG\Certificates

Using a proxy server​

Some of the features of the Pdftools SDK require access to a remote service. These features include:

If your software runs in a secured environment, it may be necessary or preferable to configure a proxy server to route requests from the Pdftools SDK to these remote services. To configure a proxy, assign the PdfTools.Sdk class a Proxy server URI that it will use for all HTTP and HTTPS communications with remote services.

Proxy server URI​

The default value for the Proxy server URI property is null, meaning that no proxy is used. Otherwise, the property’s value must be a URI with the following elements:

http[s]://[‹user›[:‹password›]@]‹host›[:‹port›]

Where:

  • http/https: Protocol for connection to proxy.
  • ‹user›:‹password› (optional): Credentials for connection to proxy (basic authorization).
  • ‹host›: Hostname of proxy.
  • ‹port›: Port for connection to proxy.

Example: http://user:password@myproxy:8080

SSL/TLS connections to online signing services​

For SSL/TLS connections (for example, to the GlobalSign or Swisscom signature services), the proxy must allow HTTP CONNECT requests to the remote server.

Connections to time-stamp authorities​

If you want to sign documents using time-stamp certificates, the following MIME types must be supported:

  • application/timestamp-query
  • application/timestamp-reply

Embedded long-term validation information​

If you plan to embed long-term validation information in the digital signatures, then the following MIME types must be supported:

  • application/ocsp-request
  • application/ocsp-response