xml signature - small javadoc fixes, removed obsolete parameter from SignatureFacet interface

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

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

@@ -90,7 +90,7 @@ public class KeyInfoKeySelector extends KeySelector implements KeySelectorResult
      * Gives back the X509 certificate used during the last signature
      * verification operation.
      * 
-     * @return
+     * @return the certificate which was used to sign the xml content
      */
     public X509Certificate getSigner() {
         // The first certificate is presumably the signer.

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

@@ -84,8 +84,13 @@ public class SignatureConfig {
     private boolean includeIssuerSerial = false;
     private boolean includeKeyValue = false;
     
+    /**
+     * the time-stamp service used for XAdES-T and XAdES-X.
+     */
     private TimeStampService tspService = new TSPTimeStampService();
-    // timestamp service provider URL
+    /**
+     * timestamp service provider URL
+     */
     private String tspUrl;
     private boolean tspOldProtocol = false;
     /**
@@ -199,21 +204,6 @@ public class SignatureConfig {
         signatureFacets.add(sf);
     }
     
-    /**
-     * Gives back the used XAdES signature facet.
-     * 
-     * @return
-     */
-    public XAdESSignatureFacet getXAdESSignatureFacet() {
-        for (SignatureFacet sf : getSignatureFacets()) {
-            if (sf instanceof XAdESSignatureFacet) {
-                return (XAdESSignatureFacet)sf;
-            }
-        }
-        return null;
-    }
-    
-    
     public List<SignatureFacet> getSignatureFacets() {
         return signatureFacets;
     }

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

@@ -481,7 +481,7 @@ public class SignatureInfo implements SignatureConfigurable {
          * Allow signature facets to inject their own stuff.
          */
         for (SignatureFacet signatureFacet : signatureConfig.getSignatureFacets()) {
-            signatureFacet.postSign(document, signatureConfig.getSigningCertificateChain());
+            signatureFacet.postSign(document);
         }
 
         writeDocument(document);

src/ooxml/java/org/apache/poi/poifs/crypt/dsig/facets/EnvelopedSignatureFacet.java

@@ -26,7 +26,6 @@ package org.apache.poi.poifs.crypt.dsig.facets;
 
 import java.security.InvalidAlgorithmParameterException;
 import java.security.NoSuchAlgorithmException;
-import java.security.cert.X509Certificate;
 import java.util.ArrayList;
 import java.util.List;
 
@@ -56,7 +55,7 @@ public class EnvelopedSignatureFacet implements SignatureFacet {
     }
     
     @Override
-    public void postSign(Document document, List<X509Certificate> signingCertificateChain) {
+    public void postSign(Document document) {
         // empty
     }
 

src/ooxml/java/org/apache/poi/poifs/crypt/dsig/facets/KeyInfoSignatureFacet.java

@@ -71,7 +71,7 @@ public class KeyInfoSignatureFacet implements SignatureFacet {
     }
 
     @Override
-    public void postSign(Document document, List<X509Certificate> signingCertificateChain) 
+    public void postSign(Document document) 
     throws MarshalException {
         LOG.log(POILogger.DEBUG, "postSign");
 
@@ -88,7 +88,7 @@ public class KeyInfoSignatureFacet implements SignatureFacet {
          */
         KeyInfoFactory keyInfoFactory = SignatureInfo.getKeyInfoFactory();
         List<Object> x509DataObjects = new ArrayList<Object>();
-        X509Certificate signingCertificate = signingCertificateChain.get(0);
+        X509Certificate signingCertificate = signatureConfig.getSigningCertificateChain().get(0);
 
         List<Object> keyInfoContent = new ArrayList<Object>();
 
@@ -109,7 +109,7 @@ public class KeyInfoSignatureFacet implements SignatureFacet {
         }
 
         if (signatureConfig.isIncludeEntireCertificateChain()) {
-            x509DataObjects.addAll(signingCertificateChain);
+            x509DataObjects.addAll(signatureConfig.getSigningCertificateChain());
         } else {
             x509DataObjects.add(signingCertificate);
         }

src/ooxml/java/org/apache/poi/poifs/crypt/dsig/facets/OOXMLSignatureFacet.java

@@ -29,7 +29,6 @@ import java.net.URI;
 import java.net.URISyntaxException;
 import java.security.InvalidAlgorithmParameterException;
 import java.security.NoSuchAlgorithmException;
-import java.security.cert.X509Certificate;
 import java.text.DateFormat;
 import java.text.SimpleDateFormat;
 import java.util.ArrayList;
@@ -79,7 +78,7 @@ import com.microsoft.schemas.office.x2006.digsig.SignatureInfoV1Document;
  * Office OpenXML Signature Facet implementation.
  * 
  * @author fcorneli
- * @see http://msdn.microsoft.com/en-us/library/cc313071.aspx
+ * @see <a href="http://msdn.microsoft.com/en-us/library/cc313071.aspx">[MS-OFFCRYPTO]: Office Document Cryptography Structure</a>
  */
 public class OOXMLSignatureFacet implements SignatureFacet {
 
@@ -281,7 +280,7 @@ public class OOXMLSignatureFacet implements SignatureFacet {
     }
 
     @Override
-    public void postSign(Document document, List<X509Certificate> signingCertificateChain) {
+    public void postSign(Document document) {
         // empty
     }
 

src/ooxml/java/org/apache/poi/poifs/crypt/dsig/facets/Office2010SignatureFacet.java

@@ -26,7 +26,6 @@ package org.apache.poi.poifs.crypt.dsig.facets;
 
 import java.security.InvalidAlgorithmParameterException;
 import java.security.NoSuchAlgorithmException;
-import java.security.cert.X509Certificate;
 import java.util.List;
 
 import javax.xml.crypto.dsig.Reference;
@@ -67,7 +66,7 @@ public class Office2010SignatureFacet implements SignatureFacet {
     }
 
     @Override
-    public void postSign(Document document, List<X509Certificate> signingCertificateChain)
+    public void postSign(Document document)
     throws XmlException {
         // check for XAdES-BES
         NodeList nl = document.getElementsByTagNameNS(XADES_132_NS, "QualifyingProperties");

src/ooxml/java/org/apache/poi/poifs/crypt/dsig/facets/SignatureFacet.java

@@ -28,7 +28,6 @@ import java.io.IOException;
 import java.net.URISyntaxException;
 import java.security.InvalidAlgorithmParameterException;
 import java.security.NoSuchAlgorithmException;
-import java.security.cert.X509Certificate;
 import java.util.List;
 
 import javax.xml.XMLConstants;
@@ -64,15 +63,15 @@ public interface SignatureFacet extends SignatureConfigurable {
      * pre-sign phase. Via this method a signature facet implementation can add
      * signature facets to an XML signature.
      * 
-     * @param signatureFactory
-     * @param document
-     * @param signatureId
-     * @param signingCertificateChain
-     *            the optional signing certificate chain
-     * @param references
-     * @param objects
-     * @throws InvalidAlgorithmParameterException
+     * @param document the signature document to be used for imports
+     * @param signatureFactory the signature factory
+     * @param references list of reference definitions
+     * @param objects objects to be signed/included in the signature document
      * @throws NoSuchAlgorithmException
+     * @throws InvalidAlgorithmParameterException
+     * @throws IOException
+     * @throws URISyntaxException
+     * @throws XmlException
      */
     void preSign(
           Document document
@@ -85,12 +84,12 @@ public interface SignatureFacet extends SignatureConfigurable {
      * This method is being invoked by the XML signature service engine during
      * the post-sign phase. Via this method a signature facet can extend the XML
      * signatures with for example key information.
-     * 
-     * @param signatureElement
-     * @param signingCertificateChain
+     *
+     * @param document the signature document to be modified
+     * @throws MarshalException
+     * @throws XmlException
      */
     void postSign(
           Document document
-        , List<X509Certificate> signingCertificateChain
     ) throws MarshalException, XmlException;
 }

src/ooxml/java/org/apache/poi/poifs/crypt/dsig/facets/XAdESSignatureFacet.java

@@ -86,7 +86,7 @@ import org.w3c.dom.Element;
  * participated multiple ETSI XAdES plugtests.
  * 
  * @author Frank Cornelis
- * @see http://en.wikipedia.org/wiki/XAdES
+ * @see <a href="http://en.wikipedia.org/wiki/XAdES">XAdES</a>
  * 
  */
 public class XAdESSignatureFacet implements SignatureFacet {
@@ -104,7 +104,7 @@ public class XAdESSignatureFacet implements SignatureFacet {
     }
 
     @Override
-    public void postSign(Document document, List<X509Certificate> signingCertificateChain) {
+    public void postSign(Document document) {
         LOG.log(POILogger.DEBUG, "postSign");
     }
 
@@ -226,12 +226,10 @@ public class XAdESSignatureFacet implements SignatureFacet {
 
     /**
      * Gives back the JAXB DigestAlgAndValue data structure.
-     * 
-     * @param data
-     * @param xadesObjectFactory
-     * @param xmldsigObjectFactory
-     * @param hashAlgo
-     * @return
+     *
+     * @param digestAlgAndValue the parent for the new digest element 
+     * @param data the data to be digested
+     * @param digestAlgo the digest algorithm
      */
     protected static void setDigestAlgAndValue(
             DigestAlgAndValueType digestAlgAndValue,

src/ooxml/java/org/apache/poi/poifs/crypt/dsig/facets/XAdESXLSignatureFacet.java

@@ -120,15 +120,6 @@ public class XAdESXLSignatureFacet implements SignatureFacet {
          this.signatureConfig = signatureConfig;
     }
     
-
-    
-    /**
-     * Convenience constructor.
-     * 
-     * @param timeStampService
-     *            the time-stamp service used for XAdES-T and XAdES-X.
-     * @param revocationDataService
-     */
     public XAdESXLSignatureFacet() {
         try {
             this.certificateFactory = CertificateFactory.getInstance("X.509");
@@ -142,9 +133,7 @@ public class XAdESXLSignatureFacet implements SignatureFacet {
     }
 
     @Override
-    public void postSign(Document document,
-        List<X509Certificate> signingCertificateChain
-    ) throws XmlException {
+    public void postSign(Document document) throws XmlException {
         LOG.log(POILogger.DEBUG, "XAdES-X-L post sign phase");
 
         QualifyingPropertiesDocument qualDoc = null;
@@ -207,9 +196,10 @@ public class XAdESXLSignatureFacet implements SignatureFacet {
          * We skip the signing certificate itself according to section
          * 4.4.3.2 of the XAdES 1.4.1 specification.
          */
-        int chainSize = signingCertificateChain.size();
+        List<X509Certificate> certChain = signatureConfig.getSigningCertificateChain();
+        int chainSize = certChain.size();
         if (chainSize > 1) {
-            for (X509Certificate cert : signingCertificateChain.subList(1, chainSize)) {
+            for (X509Certificate cert : certChain.subList(1, chainSize)) {
                 CertIDType certId = certIdList.addNewCert();
                 XAdESSignatureFacet.setCertID(certId, signatureConfig, false, cert);
             }
@@ -219,7 +209,7 @@ public class XAdESXLSignatureFacet implements SignatureFacet {
         CompleteRevocationRefsType completeRevocationRefs = 
             unsignedSigProps.addNewCompleteRevocationRefs();
         RevocationData revocationData = signatureConfig.getRevocationDataService()
-            .getRevocationData(signingCertificateChain);
+            .getRevocationData(certChain);
         if (revocationData.hasCRLs()) {
             CRLRefsType crlRefs = completeRevocationRefs.addNewCRLRefs();
             completeRevocationRefs.setCRLRefs(crlRefs);
@@ -309,7 +299,7 @@ public class XAdESXLSignatureFacet implements SignatureFacet {
 
         // XAdES-X-L
         CertificateValuesType certificateValues = unsignedSigProps.addNewCertificateValues();
-        for (X509Certificate certificate : signingCertificateChain) {
+        for (X509Certificate certificate : certChain) {
             EncapsulatedPKIDataType encapsulatedPKIDataType = certificateValues.addNewEncapsulatedX509Certificate();
             try {
                 encapsulatedPKIDataType.setByteArrayValue(certificate.getEncoded());

src/ooxml/java/org/apache/poi/poifs/crypt/dsig/services/RevocationData.java

@@ -86,7 +86,7 @@ public class RevocationData {
     /**
      * Gives back a list of all CRLs.
      * 
-     * @return
+     * @return a list of all CRLs
      */
     public List<byte[]> getCRLs() {
         return this.crls;
@@ -95,7 +95,7 @@ public class RevocationData {
     /**
      * Gives back a list of all OCSP responses.
      * 
-     * @return
+     * @return a list of all OCSP response
      */
     public List<byte[]> getOCSPs() {
         return this.ocsps;
@@ -105,7 +105,8 @@ public class RevocationData {
      * Returns <code>true</code> if this revocation data set holds OCSP
      * responses.
      * 
-     * @return
+     * @return <code>true</code> if this revocation data set holds OCSP
+     * responses.
      */
     public boolean hasOCSPs() {
         return false == this.ocsps.isEmpty();
@@ -114,7 +115,7 @@ public class RevocationData {
     /**
      * Returns <code>true</code> if this revocation data set holds CRLs.
      * 
-     * @return
+     * @return <code>true</code> if this revocation data set holds CRLs.
      */
     public boolean hasCRLs() {
         return false == this.crls.isEmpty();
@@ -123,7 +124,7 @@ public class RevocationData {
     /**
      * Returns <code>true</code> if this revocation data is not empty.
      * 
-     * @return
+     * @return <code>true</code> if this revocation data is not empty.
      */
     public boolean hasRevocationDataEntries() {
         return hasOCSPs() || hasCRLs();

src/ooxml/java/org/apache/poi/poifs/crypt/dsig/services/RevocationDataService.java

@@ -40,8 +40,8 @@ public interface RevocationDataService {
      * Gives back the revocation data corresponding with the given certificate
      * chain.
      * 
-     * @param certificateChain
-     * @return
+     * @param certificateChain the certificate chain
+     * @return the revocation data corresponding with the given certificate chain.
      */
     RevocationData getRevocationData(List<X509Certificate> certificateChain);
 }

src/ooxml/java/org/apache/poi/poifs/crypt/dsig/services/SignaturePolicyService.java

@@ -35,7 +35,7 @@ public interface SignaturePolicyService {
     /**
      * Gives back the signature policy identifier URI.
      * 
-     * @return
+     * @return the signature policy identifier URI.
      */
     String getSignaturePolicyIdentifier();
 

src/ooxml/java/org/apache/poi/util/XmlSort.java

@@ -98,7 +98,7 @@ public final class XmlSort
      * attributes are not touched. When elements are reordered, all the text, comments and PIs
      * follow the element that they come immediately after.
      * @param comp a comparator that is to be used when comparing the <code>QName</code>s of two
-     * elements. See {@link org.apache.xmlbeans.samples.cursor.XmlSort.QNameComparator} for a simple
+     * elements. See {@link QNameComparator} for a simple
      * implementation that compares two elements based on the value of their QName, but more
      * complicated implementations are possible, for instance, ones that compare two elements based
      * on the value of a specifc attribute etc.