removed obsolete classes and added a few javadocs elements and example calls

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1629095 13f79535-47bb-0310-9956-ffa450edef68

src/ooxml/java/org/apache/poi/poifs/crypt/dsig/DigestInfo.java

@@ -22,7 +22,7 @@
    Copyright (C) 2008-2014 FedICT.
    ================================================================= */ 
 
-package org.apache.poi.poifs.crypt.dsig.spi;
+package org.apache.poi.poifs.crypt.dsig;
 
 import java.io.Serializable;
 

src/ooxml/java/org/apache/poi/poifs/crypt/dsig/SignatureConfig.java

@@ -46,8 +46,6 @@ import org.apache.poi.poifs.crypt.dsig.services.SignaturePolicyService;
 import org.apache.poi.poifs.crypt.dsig.services.TSPTimeStampService;
 import org.apache.poi.poifs.crypt.dsig.services.TimeStampService;
 import org.apache.poi.poifs.crypt.dsig.services.TimeStampServiceValidator;
-import org.apache.poi.poifs.crypt.dsig.spi.AddressDTO;
-import org.apache.poi.poifs.crypt.dsig.spi.IdentityDTO;
 import org.w3c.dom.events.EventListener;
 
 /**
@@ -69,9 +67,6 @@ public class SignatureConfig {
     private Date executionTime = new Date();
     private PrivateKey key;
     private List<X509Certificate> signingCertificateChain;
-    private IdentityDTO identity;
-    private AddressDTO address;
-    private byte[] photo;
 
     /**
      * the optional signature policy service used for XAdES-EPES.
@@ -235,24 +230,6 @@ public class SignatureConfig {
             List<X509Certificate> signingCertificateChain) {
         this.signingCertificateChain = signingCertificateChain;
     }
-    public IdentityDTO getIdentity() {
-        return identity;
-    }
-    public void setIdentity(IdentityDTO identity) {
-        this.identity = identity;
-    }
-    public AddressDTO getAddress() {
-        return address;
-    }
-    public void setAddress(AddressDTO address) {
-        this.address = address;
-    }
-    public byte[] getPhoto() {
-        return photo;
-    }
-    public void setPhoto(byte[] photo) {
-        this.photo = photo;
-    }
     public Date getExecutionTime() {
         return executionTime;
     }

src/ooxml/java/org/apache/poi/poifs/crypt/dsig/SignatureInfo.java

@@ -90,7 +90,6 @@ import org.apache.poi.poifs.crypt.CryptoFunctions;
 import org.apache.poi.poifs.crypt.dsig.SignatureConfig.SignatureConfigurable;
 import org.apache.poi.poifs.crypt.dsig.facets.SignatureFacet;
 import org.apache.poi.poifs.crypt.dsig.services.RelationshipTransformService;
-import org.apache.poi.poifs.crypt.dsig.spi.DigestInfo;
 import org.apache.poi.util.DocumentHelper;
 import org.apache.poi.util.POILogFactory;
 import org.apache.poi.util.POILogger;
@@ -106,6 +105,74 @@ import org.w3c.dom.events.EventListener;
 import org.w3c.dom.events.EventTarget;
 import org.xml.sax.SAXException;
 
+
+/**
+ * <p>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.</p>
+ * 
+ * <p><b>Validating a signed office document</b></p>
+ * 
+ * <pre>
+ * OPCPackage pkg = OPCPackage.open(..., PackageAccess.READ);
+ * SignatureConfig sic = new SignatureConfig();
+ * sic.setOpcPackage(pkg);
+ * SignatureInfo si = new SignatureInfo();
+ * si.setSignatureConfig(sic);
+ * boolean isValid = si.validate();
+ * ...
+ * </pre>
+ * 
+ * <p><b>Signing a office document</b></p>
+ * 
+ * <pre>
+ * // loading the keystore - pkcs12 is used here, but of course jks &amp; 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);
+ * 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();
+ * </pre>
+ * 
+ * <p><b>Implementation notes:</b></p>
+ * 
+ * <p>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.</p>
+ * 
+ * <p>To use SignatureInfo and its sibling classes, you'll need to have the following libs
+ * in the classpath:</p>
+ * <ul>
+ * <li>BouncyCastle bcpkix and bcprov (tested against 1.51)</li>
+ * <li>Apache Santuario "xmlsec" (tested against 2.0.1)</li>
+ * <li>and slf4j-api (tested against 1.7.7)</li>
+ * </ul>
+ */
 public class SignatureInfo implements SignatureConfigurable {
 
     private static final POILogger LOG = POILogFactory.getLogger(SignatureInfo.class);

src/ooxml/java/org/apache/poi/poifs/crypt/dsig/spi/AddressDTO.java

@@ -1,51 +0,0 @@
-/* ====================================================================
-   Licensed to the Apache Software Foundation (ASF) under one or more
-   contributor license agreements.  See the NOTICE file distributed with
-   this work for additional information regarding copyright ownership.
-   The ASF licenses this file to You under the Apache License, Version 2.0
-   (the "License"); you may not use this file except in compliance with
-   the License.  You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
-==================================================================== */
-
-/* ====================================================================
-   This product contains an ASLv2 licensed version of the OOXML signer
-   package from the eID Applet project
-   http://code.google.com/p/eid-applet/source/browse/trunk/README.txt  
-   Copyright (C) 2008-2014 FedICT.
-   ================================================================= */ 
-
-package org.apache.poi.poifs.crypt.dsig.spi;
-
-import java.io.Serializable;
-import java.security.Identity;
-
-/**
- * Address Data Transfer Object.
- * 
- * @author Frank Cornelis
- * @see Identity
- * 
- */
-public class AddressDTO implements Serializable {
-
-    /*
-     * We implement serializable to allow this class to be used in distributed
-     * containers as defined in the Servlet v2.4 specification.
-     */
-
-    private static final long serialVersionUID = 1L;
-
-    public String streetAndNumber;
-
-    public String zip;
-
-    public String city;
-}

src/ooxml/java/org/apache/poi/poifs/crypt/dsig/spi/IdentityDTO.java

@@ -1,75 +0,0 @@
-/* ====================================================================
-   Licensed to the Apache Software Foundation (ASF) under one or more
-   contributor license agreements.  See the NOTICE file distributed with
-   this work for additional information regarding copyright ownership.
-   The ASF licenses this file to You under the Apache License, Version 2.0
-   (the "License"); you may not use this file except in compliance with
-   the License.  You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
-==================================================================== */
-
-/* ====================================================================
-   This product contains an ASLv2 licensed version of the OOXML signer
-   package from the eID Applet project
-   http://code.google.com/p/eid-applet/source/browse/trunk/README.txt  
-   Copyright (C) 2008-2014 FedICT.
-   ================================================================= */ 
-
-package org.apache.poi.poifs.crypt.dsig.spi;
-
-import java.io.Serializable;
-import java.util.GregorianCalendar;
-
-/**
- * Identity Data Transfer Object.
- * 
- * @author Frank Cornelis
- * 
- */
-public class IdentityDTO implements Serializable {
-
-    /*
-     * We implement serializable to allow this class to be used in distributed
-     * containers as defined in the Servlet v2.4 specification.
-     */
-    private static final long serialVersionUID = 1L;
-
-    public String cardNumber;
-
-    public String chipNumber;
-
-    public GregorianCalendar cardValidityDateBegin;
-
-    public GregorianCalendar cardValidityDateEnd;
-
-    public String cardDeliveryMunicipality;
-
-    public String nationalNumber;
-
-    public String name;
-
-    public String firstName;
-
-    public String middleName;
-
-    public String nationality;
-
-    public String placeOfBirth;
-
-    public GregorianCalendar dateOfBirth;
-
-    public boolean male;
-
-    public boolean female;
-
-    public String nobleCondition;
-
-    public String duplicate;
-}

src/ooxml/testcases/org/apache/poi/poifs/crypt/TestSignatureInfo.java

@@ -55,6 +55,7 @@ import java.util.TimeZone;
 import org.apache.poi.POIDataSamples;
 import org.apache.poi.openxml4j.opc.OPCPackage;
 import org.apache.poi.openxml4j.opc.PackageAccess;
+import org.apache.poi.poifs.crypt.dsig.DigestInfo;
 import org.apache.poi.poifs.crypt.dsig.SignatureConfig;
 import org.apache.poi.poifs.crypt.dsig.SignatureInfo;
 import org.apache.poi.poifs.crypt.dsig.SignatureInfo.SignaturePart;
@@ -66,7 +67,6 @@ import org.apache.poi.poifs.crypt.dsig.services.RevocationData;
 import org.apache.poi.poifs.crypt.dsig.services.RevocationDataService;
 import org.apache.poi.poifs.crypt.dsig.services.TimeStampService;
 import org.apache.poi.poifs.crypt.dsig.services.TimeStampServiceValidator;
-import org.apache.poi.poifs.crypt.dsig.spi.DigestInfo;
 import org.apache.poi.util.DocumentHelper;
 import org.apache.poi.util.IOUtils;
 import org.apache.poi.util.POILogFactory;