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
All Implemented Interfaces:
AutoCloseable
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 Details

    • Provider

      public Provider()

  • Method Details

    • createSignatureFromCertificate

      public SignatureConfiguration createSignatureFromCertificate(Stream stream, 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.
      IllegalArgumentException - The certificate is not a valid signing certificate
      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, String format, 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:
      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:
      IllegalArgumentException - if format is null
      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:
      IllegalArgumentException - if signature is null

    • getTimestampUrl

      public 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]://[‹user›[:‹password›]@]‹host›[:‹port›][/‹resource›]

      Where:

      • http/https: Protocol for connection to TSA.
      • ‹user›:‹password› (optional): Credentials for connection to TSA (basic authorization).
      • ‹host›: Hostname of TSA.
      • ‹port›: Port for connection to TSA.
      • ‹resource›: 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(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]://[‹user›[:‹password›]@]‹host›[:‹port›][/‹resource›]

      Where:

      • http/https: Protocol for connection to TSA.
      • ‹user›:‹password› (optional): Credentials for connection to TSA (basic authorization).
      • ‹host›: Hostname of TSA.
      • ‹port›: Port for connection to TSA.
      • ‹resource›: 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