Package com.pdftools.crypto.providers.builtin

Class Provider

  • All Implemented Interfaces:
    java.lang.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 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

      • 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:
        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]://[‹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​(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]://[‹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