Improve documentation and naming for signature integrity, authenticity and document coverage checks

DEVSIX-2744

Author: yulian-gaponenko

sign/src/main/java/com/itextpdf/signatures/LtvVerification.java

@@ -193,7 +193,7 @@ public LtvVerification(PdfDocument document, String securityProviderCode){
     public boolean addVerification(String signatureName, IOcspClient ocsp, ICrlClient crl, CertificateOption certOption, Level level, CertificateInclusion certInclude) throws IOException, GeneralSecurityException {
         if (used)
             throw new IllegalStateException(PdfException.VerificationAlreadyOutput);
-        PdfPKCS7 pk = sgnUtil.verifySignature(signatureName, securityProviderCode);
+        PdfPKCS7 pk = sgnUtil.readSignatureData(signatureName, securityProviderCode);
         LOGGER.info("Adding verification for " + signatureName);
         Certificate[] xc = pk.getCertificates();
         X509Certificate cert;

sign/src/main/java/com/itextpdf/signatures/LtvVerifier.java

@@ -364,14 +364,14 @@ protected void initLtvVerifier(PdfDocument document) throws GeneralSecurityExcep
      * @throws GeneralSecurityException
      */
     protected PdfPKCS7 coversWholeDocument() throws GeneralSecurityException {
-        PdfPKCS7 pkcs7 = sgnUtil.verifySignature(signatureName, securityProviderCode);
+        PdfPKCS7 pkcs7 = sgnUtil.readSignatureData(signatureName, securityProviderCode);
         if (sgnUtil.signatureCoversWholeDocument(signatureName)) {
             LOGGER.info("The timestamp covers whole document.");
         }
         else {
             throw new VerificationException((Certificate) null, "Signature doesn't cover whole document.");
         }
-        if (pkcs7.verify()) {
+        if (pkcs7.verifySignatureIntegrityAndAuthenticity()) {
             LOGGER.info("The signed document has not been modified.");
             return pkcs7;
         }

sign/src/main/java/com/itextpdf/signatures/PdfPKCS7.java

@@ -1162,10 +1162,34 @@ private DERSet getAuthenticatedAttributeSet(byte[] secondDigest, Collection<byte
      * Verify the digest.
      *
      * @return <CODE>true</CODE> if the signature checks out, <CODE>false</CODE> otherwise
-     * @throws SignatureException                     on error
-     * @throws java.security.GeneralSecurityException
+     * @throws java.security.GeneralSecurityException if this signature object is not initialized properly,
+     * the passed-in signature is improperly encoded or of the wrong type, if this signature algorithm is unable to
+     * process the input data provided, if the public key is invalid or if security provider or signature algorithm
+     * are not recognized, etc.
+     * @deprecated This method will be removed in future versions. Please use {@link #verifySignatureIntegrityAndAuthenticity()} instead.
      */
+    @Deprecated
     public boolean verify() throws GeneralSecurityException {
+        return verifySignatureIntegrityAndAuthenticity();
+    }
+
+    /**
+     * Verifies that signature integrity is intact (or in other words that signed data wasn't modified)
+     * by checking that embedded data digest corresponds to the calculated one. Also ensures that signature
+     * is genuine and is created by the owner of private key that corresponds to the declared public certificate.
+     * <p>
+     * Even though signature can be authentic and signed data integrity can be intact,
+     * one shall also always check that signed data is not only a part of PDF contents but is actually a complete PDF file.
+     * In order to check that given signature covers the current {@link com.itextpdf.kernel.pdf.PdfDocument} please
+     * use {@link SignatureUtil#signatureCoversWholeDocument(String)} method.
+     * </p>
+     * @return <CODE>true</CODE> if the signature checks out, <CODE>false</CODE> otherwise
+     * @throws java.security.GeneralSecurityException if this signature object is not initialized properly,
+     * the passed-in signature is improperly encoded or of the wrong type, if this signature algorithm is unable to
+     * process the input data provided, if the public key is invalid or if security provider or signature algorithm
+     * are not recognized, etc.
+     */
+    public boolean verifySignatureIntegrityAndAuthenticity() throws GeneralSecurityException {
         if (verified)
             return verifyResult;
         if (isTsp) {

sign/src/main/java/com/itextpdf/signatures/SignatureUtil.java

@@ -116,26 +116,91 @@ public SignatureUtil(PdfDocument document) {
     }
 
     /**
-     * Verifies a signature. Further verification can be done on the returned
-     * {@link PdfPKCS7} object.
+     * Prepares an {@link PdfPKCS7} instance for the given signature.
+     * This method handles signature parsing and might throw an exception if
+     * signature is malformed.
+     * <p>
+     * The returned {@link PdfPKCS7} can be used to fetch additional info about the signature
+     * and also to perform integrity check of data signed by the given signature field.
+     * </p>
+     * In order to check that given signature covers the current PdfDocument revision please
+     * use {@link #signatureCoversWholeDocument(String)} method.
      *
-     * @param name String the signature field name
-     * @return PdfPKCS7 object to continue the verification
+     * @param name     the signature field name
+     * @return a {@link PdfPKCS7} instance which can be used to fetch additional info about the signature
+     * and also to perform integrity check of data signed by the given signature field.
+     * @deprecated This method is deprecated and will be removed in future versions.
+     * Please use {@link #readSignatureData(String)} instead.
      */
+    @Deprecated
     public PdfPKCS7 verifySignature(String name) {
-        return verifySignature(name, null);
+        return readSignatureData(name, null);
     }
 
     /**
-     * Verifies a signature. Further verification can be done on the returned
-     * {@link PdfPKCS7} object.
+     * Prepares an {@link PdfPKCS7} instance for the given signature.
+     * This method handles signature parsing and might throw an exception if
+     * signature is malformed.
+     * <p>
+     * The returned {@link PdfPKCS7} can be used to fetch additional info about the signature
+     * and also to perform integrity check of data signed by the given signature field.
+     * </p>
+     * In order to check that given signature covers the current PdfDocument revision please
+     * use {@link #signatureCoversWholeDocument(String)} method.
      *
      * @param name     the signature field name
-     * @param provider the provider or null for the default provider
-     * @return PdfPKCS7 object to continue the verification
+     * @param provider the security provider or null for the default provider
+     * @return a {@link PdfPKCS7} instance which can be used to fetch additional info about the signature
+     * and also to perform integrity check of data signed by the given signature field.
+     * @deprecated This method is deprecated and will be removed in future versions.
+     * Please use {@link #readSignatureData(String, String)} instead.
      */
+    @Deprecated
     public PdfPKCS7 verifySignature(String name, String provider) {
-        PdfSignature signature = getSignature(name);
+        return readSignatureData(name, provider);
+    }
+
+    /**
+     * Prepares an {@link PdfPKCS7} instance for the given signature.
+     * This method handles signature parsing and might throw an exception if
+     * signature is malformed.
+     * <p>
+     * The returned {@link PdfPKCS7} can be used to fetch additional info about the signature
+     * and also to perform integrity check of data signed by the given signature field.
+     * </p>
+     * In order to validate the signature it is required to check if it covers the entire file,
+     * otherwise one cannot be sure that signature in question indeed signs the data
+     * that constitutes current {@link PdfDocument} with all its contents.
+     * In order to check that given signature covers the current {@link PdfDocument} please
+     * use {@link #signatureCoversWholeDocument(String)} method.
+     *
+     * @param signatureFieldName the signature field name
+     * @return a {@link PdfPKCS7} instance which can be used to fetch additional info about the signature
+     * and also to perform integrity check of data signed by the given signature field.
+     */
+    public PdfPKCS7 readSignatureData(String signatureFieldName) {
+        return readSignatureData(signatureFieldName, null);
+    }
+
+    /**
+     * Prepares an {@link PdfPKCS7} instance for the given signature.
+     * This method handles signature parsing and might throw an exception if
+     * signature is malformed.
+     * <p>
+     * The returned {@link PdfPKCS7} can be used to fetch additional info about the signature
+     * and also to perform integrity check of data signed by the given signature field.
+     * </p>
+     * Prepared {@link PdfPKCS7} instance calculates digest based on signature's /ByteRange entry.
+     * In order to check that /ByteRange is properly defined and given signature indeed covers the current PDF document
+     * revision please use {@link #signatureCoversWholeDocument(String)} method.
+     *
+     * @param signatureFieldName the signature field name
+     * @param securityProvider the security provider or null for the default provider
+     * @return a {@link PdfPKCS7} instance which can be used to fetch additional info about the signature
+     * and also to perform integrity check of data signed by the given signature field.
+     */
+    public PdfPKCS7 readSignatureData(String signatureFieldName, String securityProvider) {
+        PdfSignature signature = getSignature(signatureFieldName);
         if (signature == null)
             return null;
         try {
@@ -146,9 +211,9 @@ public PdfPKCS7 verifySignature(String name, String provider) {
                 PdfString cert = signature.getPdfObject().getAsString(PdfName.Cert);
                 if (cert == null)
                     cert = signature.getPdfObject().getAsArray(PdfName.Cert).getAsString(0);
-                pk = new PdfPKCS7(PdfEncodings.convertToBytes(contents.getValue(), null), cert.getValueBytes(), provider);
+                pk = new PdfPKCS7(PdfEncodings.convertToBytes(contents.getValue(), null), cert.getValueBytes(), securityProvider);
             } else
-                pk = new PdfPKCS7(PdfEncodings.convertToBytes(contents.getValue(), null), sub, provider);
+                pk = new PdfPKCS7(PdfEncodings.convertToBytes(contents.getValue(), null), sub, securityProvider);
             updateByteRange(pk, signature);
             PdfString date = signature.getDate();
             if (date != null)
@@ -289,7 +354,11 @@ public InputStream extractRevision(String field) throws IOException {
 
     /**
      * Checks if the signature covers the entire document (except for signature's Contents) or just a part of it.
-     *
+     * <p>
+     * If this method does not return {@code true} it means that signature in question does not cover the entire
+     * contents of current {@link PdfDocument}. Such signatures cannot be considered as verifying the PDF document,
+     * because content that is not covered by signature might have been modified since the signature creation.
+     * </p>
      * @param name the signature field name
      * @return true if the signature covers the entire document, false if it doesn't
      */

sign/src/test/java/com/itextpdf/signatures/sign/PadesSigTest.java

@@ -169,8 +169,8 @@ static void basicCheckSignedDoc(String filePath, String signatureName) throws Ge
         PdfDocument outDocument = new PdfDocument(new PdfReader(filePath));
 
         SignatureUtil sigUtil = new SignatureUtil(outDocument);
-        PdfPKCS7 pdfPKCS7 = sigUtil.verifySignature(signatureName);
-        Assert.assertTrue(pdfPKCS7.verify());
+        PdfPKCS7 signatureData = sigUtil.readSignatureData(signatureName);
+        Assert.assertTrue(signatureData.verifySignatureIntegrityAndAuthenticity());
 
         outDocument.close();
     }

sign/src/test/java/com/itextpdf/signatures/verify/pdfinsecurity/IncrementalSavingAttackTest.java

@@ -38,8 +38,8 @@ public void testISA03() throws IOException, GeneralSecurityException {
 
         PdfDocument document = new PdfDocument(new PdfReader(filePath));
         SignatureUtil sigUtil = new SignatureUtil(document);
-        PdfPKCS7 pdfPKCS7 = sigUtil.verifySignature(signatureName);
-        Assert.assertTrue(pdfPKCS7.verify());
+        PdfPKCS7 pdfPKCS7 = sigUtil.readSignatureData(signatureName);
+        Assert.assertTrue(pdfPKCS7.verifySignatureIntegrityAndAuthenticity());
         Assert.assertFalse(sigUtil.signatureCoversWholeDocument(signatureName));
         document.close();
     }
@@ -51,8 +51,8 @@ public void testISAValidPdf() throws IOException, GeneralSecurityException {
 
         PdfDocument document = new PdfDocument(new PdfReader(filePath));
         SignatureUtil sigUtil = new SignatureUtil(document);
-        PdfPKCS7 pdfPKCS7 = sigUtil.verifySignature(signatureName);
-        Assert.assertTrue(pdfPKCS7.verify());
+        PdfPKCS7 pdfPKCS7 = sigUtil.readSignatureData(signatureName);
+        Assert.assertTrue(pdfPKCS7.verifySignatureIntegrityAndAuthenticity());
         Assert.assertFalse(sigUtil.signatureCoversWholeDocument(signatureName));
 
         String textFromPage = PdfTextExtractor.getTextFromPage(document.getPage(1));
@@ -68,8 +68,8 @@ public void testISAValidPdf() throws IOException, GeneralSecurityException {
         PdfDocument sigRevDocument = new PdfDocument(new PdfReader(sigInputStream));
 
         SignatureUtil sigRevUtil = new SignatureUtil(sigRevDocument);
-        PdfPKCS7 sigRevSignatureData = sigRevUtil.verifySignature(signatureName);
-        Assert.assertTrue(sigRevSignatureData.verify());
+        PdfPKCS7 sigRevSignatureData = sigRevUtil.readSignatureData(signatureName);
+        Assert.assertTrue(sigRevSignatureData.verifySignatureIntegrityAndAuthenticity());
         Assert.assertTrue(sigRevUtil.signatureCoversWholeDocument(signatureName));
 
         sigRevDocument.close();

sign/src/test/java/com/itextpdf/signatures/verify/pdfinsecurity/SignatureWrappingAttackTest.java

@@ -31,8 +31,8 @@ public void testSWA01() throws IOException, GeneralSecurityException {
 
         PdfDocument document = new PdfDocument(new PdfReader(filePath));
         SignatureUtil sigUtil = new SignatureUtil(document);
-        PdfPKCS7 pdfPKCS7 = sigUtil.verifySignature(signatureName);
-        Assert.assertTrue(pdfPKCS7.verify());
+        PdfPKCS7 pdfPKCS7 = sigUtil.readSignatureData(signatureName);
+        Assert.assertTrue(pdfPKCS7.verifySignatureIntegrityAndAuthenticity());
         Assert.assertFalse(sigUtil.signatureCoversWholeDocument(signatureName));
         document.close();
     }