org.faceless.pdf2

Class GlobalSignDSSManager

java.lang.Object

org.faceless.pdf2.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 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.

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("OU=Test Unit")));
 

Signatures created by this class are long-term validated by default, and use the SHA-256 algorithm with RSA encryption.

Since:

2.22

Constructor Summary

Constructors

Constructor and Description
GlobalSignDSSManager() Create a new GlobalSign Digital Signature Service Manager.

Method Summary

Modifier and Type	Method and Description
SignatureHandlerFactory	createSignatureHandlerFactory(String subject) Creata a new SignatureHandlerFactory which will sign PDFs with credentials extracted fom the supplied String.
SignatureHandlerFactory	createSignatureHandlerFactory(X500Principal subject) Creata a new SignatureHandlerFactory which will sign PDFs with credentials extracted fom the supplied X.500 distinguished name.
SignatureHandlerFactory	createSignatureHandlerFactory(X509Certificate cert) Creata a new SignatureHandlerFactory which will sign PDFs with credentials extracted fom the supplied X.509 Certificate.
String	getValidationPolicy() Return the Validation Policy for this account.
void	setLogin(KeyStore keystore, char[] password, byte[] encrypted) Set the Login credentials to use this account.
void	setLogin(KeyStore keystore, char[] password, String apikey, String apisecret) Set the Login credentials to use this account.
void	setURL(String url) Set the URL prefix to use for all requests, for example "https://dss.globalsign.com:8443".

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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(X500Principal subject)
                                                      throws IOException,
                                                             CertificateException

Creata a new SignatureHandlerFactory which will sign PDFs with credentials extracted fom the supplied X.500 distinguished name. The returned object can be used to sign multiple signatures in multiple threads simultaneously.

Parameters:

subject - an X.500 distinguished name which will be used as the source of the identity details.

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