Package com.pdftools.crypto.providers.builtin

Class Provider

java.lang.Object

com.pdftools.internal.NativeBase

com.pdftools.internal.NativeObject

com.pdftools.crypto.providers.Provider

com.pdftools.crypto.providers.builtin.Provider

public class Provider
extends Provider

The built-in cryptographic provider

The built-in cryptographic provider requires no cryptographic hardware or external service (except for the optional getTimestampUrl()).

Signing certificates with private keys can be loaded using createSignatureFromCertificate(com.pdftools.sys.Stream, java.lang.String).

Certificates Directory: Additional certificates, e.g. issuer certificates, can be stored in the certificates directory. These certificates are required when adding validation information to signatures that do not have the full trust chain embedded. The certificates directory may contain certificates in either PEM (.pem, ASCII text) or DER (.cer, binary) form.

• Windows:
  • %LOCALAPPDATA%\PDF Tools AG\Certificates
  • %ProgramData%\PDF Tools AG\Certificates
• Linux:
  • ~/.pdf-tools/Certificates or $TMP/pdf-tools/Certificates
  • /usr/share/pdf-tools/Certificates
• macOS:
  • ~/.pdf-tools/Certificates or $TMP/pdf-tools/Certificates

Constructor Summary

Constructors

Constructor	Description
Provider()

Method Summary

Modifier and Type	Method	Description
SignatureConfiguration	createPreparedSignature(int size, java.lang.String format, java.lang.String name)	Create a configuration to prepare a signature for an external signature handler
SignatureConfiguration	createSignatureFromCertificate(Stream stream, java.lang.String password)	Create a configuration to sign with a PFX (PKCS#12) soft certificate
TimestampConfiguration	createTimestamp()	Create a time-stamp configuration
java.net.URI	getTimestampUrl()	The URL of the trusted time-stamp authority (TSA) from which time-stamps shall be acquired (Getter)
SignatureConfiguration	readExternalSignature(byte... signature)	Read signature created by an external signature handler
void	setTimestampUrl(java.net.URI value)	The URL of the trusted time-stamp authority (TSA) from which time-stamps shall be acquired (Setter)

Methods inherited from class com.pdftools.internal.NativeObject

equals, hashCode

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from class com.pdftools.crypto.providers.Provider

close

Constructor Detail

Provider

public Provider()

Method Detail

createSignatureFromCertificate

public SignatureConfiguration createSignatureFromCertificate(Stream stream,
                                                             java.lang.String password)
                                                      throws CorruptException,
                                                             PasswordException

Create a configuration to sign with a PFX (PKCS#12) soft certificate

The file must contain the certificate itself, all certificates of the trust chain, and the private key.

Parameters:

stream - The signing certificate in PKCS#12 format (.p12, .pfx).

password - The password required to decrypt the private key of the archive.

Returns:

Throws:

CorruptException - The PFX (PKCS#12) archive is corrupt and cannot be read.

PasswordException - The password is invalid.

java.lang.IllegalArgumentException - The certificate is not a valid signing certificate

java.lang.IllegalArgumentException - if stream is null

createTimestamp

public TimestampConfiguration createTimestamp()

Create a time-stamp configuration

Note that to create time-stamps, the getTimestampUrl() must be set.

Returns:

createPreparedSignature

public SignatureConfiguration createPreparedSignature(int size,
                                                      java.lang.String format,
                                                      java.lang.String name)

Create a configuration to prepare a signature for an external signature handler

This method is part of a very specialized use case requiring an external signature handler. The process using an external signature handler is:

• createPreparedSignature(int, java.lang.String, java.lang.String): Create the signature configuration.
• pdftools.sign.Signer.addPreparedSignature: Create the document with the prepared signature.
• pdftools.sign.PreparedDocument.getHash: Calculate the hash from the document and create the signature using an external signature handler.
• readExternalSignature(byte...): Create signature configuration for the external signature.
• pdftools.sign.Signer.signPreparedSignature: Insert the external signature into the document with the prepared signature.

Parameters:

size - The expected size of the cryptographic signature that will be added later. This is the number of bytes that will be reserved in the prepared signature.

format - The format (SubFilter) of the cryptographic signature that is added later. For example, "adbe.pkcs7.detached" or "ETSI.CAdES.detached".

name - The name of the signer of the cryptographic signature that will be added later.

Returns:

Throws:

java.lang.IllegalArgumentException - if format is null

java.lang.IllegalArgumentException - if name is null

readExternalSignature

public SignatureConfiguration readExternalSignature(byte... signature)

Read signature created by an external signature handler

See createPreparedSignature(int, java.lang.String, java.lang.String) for more information on the signing process using an external signature handler.

Parameters:

signature - This signature must not be larger than the number of bytes reserved in the prepared signature.

Returns:

Throws:

java.lang.IllegalArgumentException - if signature is null

getTimestampUrl

public java.net.URI getTimestampUrl()

The URL of the trusted time-stamp authority (TSA) from which time-stamps shall be acquired (Getter)

The TSA must support the time-stamp protocol as defined in RFC 3161.

The property’s value must be a URL with the following elements:

http[s]://[\u2039user\u203a[:\u2039password\u203a]@]\u2039host\u203a[:\u2039port\u203a][/\u2039resource\u203a]

Where:

• http/https: Protocol for connection to TSA.
• \u2039user\u203a:\u2039password\u203a (optional): Credentials for connection to TSA (basic authorization).
• \u2039host\u203a: Hostname of TSA.
• \u2039port\u203a: Port for connection to TSA.
• \u2039resource\u203a: The resource.

Applying a time-stamp requires an online connection to a time server; the firewall must be configured accordingly. If a web proxy is used (see pdftools.Sdk.getProxy), make sure the following MIME types are supported:

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

setTimestampUrl

public void setTimestampUrl(java.net.URI value)

The URL of the trusted time-stamp authority (TSA) from which time-stamps shall be acquired (Setter)

The TSA must support the time-stamp protocol as defined in RFC 3161.

The property’s value must be a URL with the following elements:

http[s]://[\u2039user\u203a[:\u2039password\u203a]@]\u2039host\u203a[:\u2039port\u203a][/\u2039resource\u203a]

Where:

• http/https: Protocol for connection to TSA.
• \u2039user\u203a:\u2039password\u203a (optional): Credentials for connection to TSA (basic authorization).
• \u2039host\u203a: Hostname of TSA.
• \u2039port\u203a: Port for connection to TSA.
• \u2039resource\u203a: The resource.

Applying a time-stamp requires an online connection to a time server; the firewall must be configured accordingly. If a web proxy is used (see pdftools.Sdk.getProxy), make sure the following MIME types are supported:

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