Package org.faceless.pdf2

Class GlobalSignDSSManager

  • public class GlobalSignDSSManager
extends Object

    This class creates a SignatureHandlerFactory that makes use of GlobalSign's Digital Signing Service to sign documents remotely.

    To use this class you will need login credentials and client certificate issued by GlobalSign. The client (or "mTLS") certificate must be stored in a KeyStore. You will also need details of the identity you wish to use to sign the PDF, which may be stored as an X.500 Distinguished Name, or extracted from an X.509 Certificate. Which is more appropriate wlil depend on the type of account that you have with GlobalSign, but as of 2020 we believe the most common way will be to simply specify an identity with "CN=nnn", where nnn is the name of the identity as registered with Globalsign. This is shown in the example below.

    Here's a simple example showing how to sign a PDF with this class 

     String apikey = "apikey";                    // supplied by GlobalSign
 String apisecret = "apisecret";              // supplied by GlobalSign
 String keystore = "keystore.pkcs12";         // path to KeyStore containing client certificate
 char[] password = "password".toCharArray();  // password for KeyStore

 GlobalSignDSSManager gs = new GlobalSignDSSManager();
 KeyStore keystore = KeyStore.getInstance("PKCS12");
 keystore.load(new FileInputStream(keystore), password);
 gs.setLogin(keystore, password, apikey, apisecret);
 FormSignature sig = new FormSignature();
 pdf.getForm().getElements().put("Sig1", sig);
 sig.sign(null, null, null, gs.createSignatureHandlerFactory(new X500Principal("CN=identity")));
    Signatures created by this class are long-term validated by default, and use the SHA-256 algorithm with RSA encryption.
    Since:
    2.22

    • Constructor Detail

      • GlobalSignDSSManager

        public GlobalSignDSSManager()
        Create a new GlobalSign Digital Signature Service Manager. The returned object is safe for use across multiple threads, and does not expire.

    • Method Detail

      • setURL

        public void setURL​(String url)
        Set the URL prefix to use for all requests, for example "https://dss.globalsign.com:8443". This is not typically required as the correct value (at the time of implementation) is set by default.
        Parameters:
        url - the URL prefix

      • setLogin

        public void setLogin​(KeyStore keystore,
                     char[] password,
                     byte[] encrypted)
              throws GeneralSecurityException,
                     IOException
        Set the Login credentials to use this account. This must be done before any signing attempts are made
        Parameters:
        keystore - the KeyStore containing the GlobalSign client certificate
        password - the password for that KeyStore
        encrypted - the encrypted API credentials, as supplied by GlobalSign
        Throws:
        GeneralSecurityException - if there is an issue accessing the appropriate certificate from the KeyStore
        IOException - if there is an IO exception or if globalsign rejected the transaction

      • setLogin

        public void setLogin​(KeyStore keystore,
                     char[] password,
                     String apikey,
                     String apisecret)
              throws GeneralSecurityException,
                     IOException
        Set the Login credentials to use this account. This must be done before any signing attempts are made
        Parameters:
        keystore - the KeyStore containing the GlobalSign client certificate
        password - the password for that KeyStore
        apikey - the "API key", as supplied by GlobalSign
        apisecret - the "API secret", as supplied by GlobalSign
        Throws:
        GeneralSecurityException - if there is an issue accessing the appropriate certificate from the KeyStore
        IOException - if there is an IO exception or if globalsign rejected the transaction

      • getValidationPolicy

        public String getValidationPolicy()
                           throws IOException

        Return the Validation Policy for this account. The login method must have been called already. The Validation Policy is a serialized JSON object containing details about which fields can or cannot be set in the "identity" passed to GlobalSign. A full description of this datastructure is not offered here, but a high-level description is available in GlobalSign's guide to this service.

        If attempts to sign return an HTTP 422 Exception, this value should be consulted to determine which fields are disallowed in the request.

        Throws:
        IOException

      • createSignatureHandlerFactory

        public SignatureHandlerFactory createSignatureHandlerFactory​(X509Certificate cert)
                                                      throws IOException,
                                                             CertificateException

        Creata a new SignatureHandlerFactory which will sign PDFs with credentials extracted fom the supplied X.509 Certificate. The certificate itself is used only as a source for the identity data sent to GlobalSign, so can be self-signed or unsigned.

        The following data is extracted from the certificate:

        • Subject distinguished name
        • Subject alternative names (optional)
        • Extended key usage (optional)
        • Subject directory attributes from extension 2.5.29.9 (see RFC3739) (optional)
        • Subject Qualified Statements from extension 1.3.6.1.5.5.7.1.3: specifically those defined in ETSI EN 319 412-5 V2.1.1 (optional)

        The returned object can be used to sign multiple signatures in multiple threads simultaneously.

        Parameters:
        cert - an X.509 Certificate to extract the identity details from.
        Returns:
        a SignatureHandlerFactory which can be used to sign PDFs
        Throws:
        IOException
        CertificateException

      • createSignatureHandlerFactory

        public SignatureHandlerFactory createSignatureHandlerFactory​(String subject)
                                                      throws IOException,
                                                             CertificateException
        Creata a new SignatureHandlerFactory which will sign PDFs with credentials extracted fom the supplied String. The String must be JSON-formatted and describe the structure from the GlobalSign specification. We would generally recommend an X509 Certificate or X500 principal be used instead as there is less room for error, but this this method may be useful for testing. The returned object can be used to sign multiple signatures in multiple threads simultaneously.
        Parameters:
        subject - a String representation of a JSON structure describing the subject identity, as described in the GlobalSign specification, eg {"subject_dn":{"organizational_unit":["Administration"]}}.
        Returns:
        a SignatureHandlerFactory which can be used to sign PDFs
        Throws:
        IOException
        CertificateException