org.apache.poi.poifs.crypt.dsig

Class SignatureInfo

java.lang.Object

org.apache.poi.poifs.crypt.dsig.SignatureInfo

public class SignatureInfo
extends Object

This class is the default entry point for XML signatures and can be used for validating an existing signed office document and signing a office document.

Validating a signed office document

 OPCPackage pkg = OPCPackage.open(..., PackageAccess.READ);
 SignatureConfig sic = new SignatureConfig();
 sic.setOpcPackage(pkg);
 SignatureInfo si = new SignatureInfo();
 si.setSignatureConfig(sic);
 boolean isValid = si.validate();
 ...
 

Signing an office document

 // loading the keystore - pkcs12 is used here, but of course jks & co are also valid
 // the keystore needs to contain a private key and it's certificate having a
 // 'digitalSignature' key usage
 char password[] = "test".toCharArray();
 File file = new File("test.pfx");
 KeyStore keystore = KeyStore.getInstance("PKCS12");
 FileInputStream fis = new FileInputStream(file);
 keystore.load(fis, password);
 fis.close();

 // extracting private key and certificate
 String alias = "xyz"; // alias of the keystore entry
 Key key = keystore.getKey(alias, password);
 X509Certificate x509 = (X509Certificate)keystore.getCertificate(alias);

 // filling the SignatureConfig entries (minimum fields, more options are available ...)
 SignatureConfig signatureConfig = new SignatureConfig();
 signatureConfig.setKey(keyPair.getPrivate());
 signatureConfig.setSigningCertificateChain(Collections.singletonList(x509));
 OPCPackage pkg = OPCPackage.open(..., PackageAccess.READ_WRITE);
 signatureConfig.setOpcPackage(pkg);

 // adding the signature document to the package
 SignatureInfo si = new SignatureInfo();
 si.setSignatureConfig(signatureConfig);
 si.confirmSignature();
 // optionally verify the generated signature
 boolean b = si.verifySignature();
 assert (b);
 // write the changes back to disc
 pkg.close();
 

Implementation notes:

Although there's a XML signature implementation in the Oracle JDKs 6 and higher, compatibility with IBM JDKs is also in focus (... but maybe not thoroughly tested ...). Therefore we are using the Apache Santuario libs (xmlsec) instead of the built-in classes, as the compatibility seems to be provided there.

To use SignatureInfo and its sibling classes, you'll need to have the following libs in the classpath:

• BouncyCastle bcpkix and bcprov (tested against 1.67)
• Apache Santuario "xmlsec" (tested against 2.2.0)
• and log4j-api (tested against 2.14.0)

Constructor Summary

Constructors

Constructor and Description
SignatureInfo()

Method Summary

Modifier and Type	Method and Description
void	confirmSignature() add the xml signature to the document
DOMSignContext	createXMLSignContext(Document document) Convenience method for creating the signature context
KeyInfoFactory	getKeyInfoFactory()
OPCPackage	getOpcPackage()
SignatureConfig	getSignatureConfig()
XMLSignatureFactory	getSignatureFactory()
Iterable<SignaturePart>	getSignatureParts()
URIDereferencer	getUriDereferencer()
protected void	initXmlProvider() Initialize the xml signing environment and the bouncycastle provider
void	postSign(DOMSignContext xmlSignContext, String signatureValue) Helper method for adding informations after the signing.
org.apache.jcp.xml.dsig.internal.dom.DOMSignedInfo	preSign(DOMSignContext xmlSignContext) Helper method for adding informations before the signing.
protected void	registerEventListener(Document document)
void	setKeyInfoFactory(KeyInfoFactory keyInfoFactory)
void	setOpcPackage(OPCPackage opcPackage)
void	setProvider(Provider provider)
void	setSignatureConfig(SignatureConfig signatureConfig)
void	setSignatureFactory(XMLSignatureFactory signatureFactory)
void	setUriDereferencer(URIDereferencer uriDereferencer)
String	signDigest(DOMSignContext xmlSignContext, org.apache.jcp.xml.dsig.internal.dom.DOMSignedInfo signedInfo) Sign (encrypt) the digest with the private key.
boolean	verifySignature()
protected void	writeDocument(Document document) Write XML signature into the OPC package

Methods inherited from class java.lang.Object

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

Constructor Detail

SignatureInfo

public SignatureInfo()

Method Detail

getSignatureConfig

public SignatureConfig getSignatureConfig()

Returns:

the signature config

setSignatureConfig

public void setSignatureConfig(SignatureConfig signatureConfig)

Parameters:

signatureConfig - the signature config, needs to be set before a SignatureInfo object is used

setOpcPackage

public void setOpcPackage(OPCPackage opcPackage)

getOpcPackage

public OPCPackage getOpcPackage()

getUriDereferencer

public URIDereferencer getUriDereferencer()

setUriDereferencer

public void setUriDereferencer(URIDereferencer uriDereferencer)

verifySignature

public boolean verifySignature()

Returns:

true, if first signature part is valid

confirmSignature

public void confirmSignature()
                      throws XMLSignatureException,
                             MarshalException

add the xml signature to the document

Throws:

XMLSignatureException - if the signature can't be calculated

MarshalException - if the document can't be serialized

createXMLSignContext

public DOMSignContext createXMLSignContext(Document document)

Convenience method for creating the signature context

Parameters:

document - the document the signature is based on

Returns:

the initialized signature context

signDigest

public String signDigest(DOMSignContext xmlSignContext,
                         org.apache.jcp.xml.dsig.internal.dom.DOMSignedInfo signedInfo)

Sign (encrypt) the digest with the private key. Currently only rsa is supported.

Returns:

the encrypted hash

getSignatureParts

public Iterable<SignaturePart> getSignatureParts()

Returns:

a signature part for each signature document. the parts can be validated independently.

preSign

public org.apache.jcp.xml.dsig.internal.dom.DOMSignedInfo preSign(DOMSignContext xmlSignContext)
                                                           throws XMLSignatureException,
                                                                  MarshalException

Helper method for adding informations before the signing. Normally confirmSignature() is sufficient to be used.

Throws:

XMLSignatureException

MarshalException

registerEventListener

protected void registerEventListener(Document document)

postSign

public void postSign(DOMSignContext xmlSignContext,
                     String signatureValue)
              throws MarshalException

Helper method for adding informations after the signing. Normally confirmSignature() is sufficient to be used.

Throws:

MarshalException

writeDocument

protected void writeDocument(Document document)
                      throws MarshalException

Write XML signature into the OPC package

Parameters:

document - the xml signature document

Throws:

MarshalException - if the document can't be serialized

setProvider

public void setProvider(Provider provider)

setSignatureFactory

public void setSignatureFactory(XMLSignatureFactory signatureFactory)

getSignatureFactory

public XMLSignatureFactory getSignatureFactory()

setKeyInfoFactory

public void setKeyInfoFactory(KeyInfoFactory keyInfoFactory)

getKeyInfoFactory

public KeyInfoFactory getKeyInfoFactory()

initXmlProvider

protected void initXmlProvider()

Initialize the xml signing environment and the bouncycastle provider