Fix some confusing Javadoc about OCSP

A number of methods that expect to be passed a DER-encoded
BasicOCSPResponse had confusing Javadoc suggesting that they expect a
full OCSPResponse structure, but do not do any sanity checking.
This causes iText to output botched ASN.1 structures without informing the
user.

RES-382

Author: MatthiasValvekens

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

@@ -51,13 +51,21 @@ This file is part of the iText (R) project.
 public interface IOcspClient {
 
     /**
-     * Gets an encoded byte array with OCSP validation. The method should not throw an exception.
+     * Fetch a DER-encoded BasicOCSPResponse from an OCSP responder. The method should not throw
+     * an exception.
+     *
+     * <p>
+     *     Note: do not pass in the full DER-encoded OCSPResponse object obtained from the responder,
+     *     only the DER-encoded BasicOCSPResponse value contained in the response data.
      *
      * @param checkCert  Certificate to check.
      * @param issuerCert The parent certificate.
-     * @param url        The url to get the verification. It it's null it will be taken.
-     *                   from the check cert or from other implementation specific source
-     * @return A byte array with the validation or null if the validation could not be obtained
+     * @param url        The URL of the OCSP responder endpoint. If null, implementations can
+     *                   attempt to obtain a URL from the AuthorityInformationAccess extension of
+     *                   the certificate, or from another implementation-specific source.
+     * @return a byte array containing a DER-encoded BasicOCSPResponse structure or null if one
+     *         could not be obtained
+     * @see <a href="https://datatracker.ietf.org/doc/html/rfc6960#section-4.2.1">RFC 6960 § 4.2.1</a>
      */
     byte[] getEncoded(X509Certificate checkCert, X509Certificate issuerCert, String url);
 }

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

@@ -269,9 +269,9 @@ private X509Certificate getParent(X509Certificate cert, Certificate[] certs) {
      * Adds verification to the signature.
      *
      * @param signatureName name of the signature
-     * @param ocsps collection of ocsp responses
-     * @param crls collection of crls
-     * @param certs collection of certificates
+     * @param ocsps collection of DER-encoded BasicOCSPResponses
+     * @param crls collection of DER-encoded CRLs
+     * @param certs collection of DER-encoded certificates
      * @return boolean
      * @throws IOException signals that an I/O exception has occurred
      * @throws GeneralSecurityException when requested cryptographic algorithm or security provider

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

@@ -121,13 +121,7 @@ public BasicOCSPResp getBasicOCSPResp(X509Certificate checkCert, X509Certificate
     }
 
     /**
-     * Gets an encoded byte array with OCSP validation. The method should not throw an exception.
-     *
-     * @param checkCert to certificate to check
-     * @param rootCert  the parent certificate
-     * @param url       to get the verification. It it's null it will be taken
-     *                  from the check cert or from other implementation specific source
-     * @return a byte array with the validation or null if the validation could not be obtained
+     * {@inheritDoc}
      */
     @Override
     public byte[] getEncoded(X509Certificate checkCert, X509Certificate rootCert, String url) {

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

@@ -798,12 +798,20 @@ public byte[] getEncodedPKCS7(byte[] secondDigest) {
      * in the signerInfo can also be set, and/or a time-stamp-authority client
      * may be provided.
      *
+     * <p>
+     *     Note: do not pass in the full DER-encoded OCSPResponse object obtained from the responder,
+     *     only the DER-encoded BasicOCSPResponse value contained in the response data.
+     *
      * @param secondDigest the digest in the authenticatedAttributes
      * @param tsaClient    TSAClient - null or an optional time stamp authority client
-     * @param ocsp DER-encoded OCSP response for the first certificate in the signature certificates chain, or null if OCSP revocation data is not to be added.
-     * @param crlBytes collection of DER-encoded CRL for certificates from the signature certificates chain, or null if CRL revocation data is not to be added.
-     * @param sigtype specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere: either basic CMS or CAdES
+     * @param ocsp DER-encoded BasicOCSPResponse for the first certificate in the signature certificates chain,
+     *             or null if OCSP revocation data is not to be added.
+     * @param crlBytes collection of DER-encoded CRL for certificates from the signature certificates chain,
+     *                 or null if CRL revocation data is not to be added.
+     * @param sigtype specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere:
+     *                either basic CMS or CAdES
      * @return byte[] the bytes for the PKCS7SignedData object
+     * @see <a href="https://datatracker.ietf.org/doc/html/rfc6960#section-4.2.1">RFC 6960 § 4.2.1</a>
      * @deprecated This overload is deprecated, use {@link #getEncodedPKCS7(byte[], PdfSigner.CryptoStandard, ITSAClient, Collection, Collection)} instead.
      */
     @Deprecated
@@ -816,11 +824,18 @@ public byte[] getEncodedPKCS7(byte[] secondDigest, ITSAClient tsaClient, byte[]
      * in the signerInfo can also be set, and/or a time-stamp-authority client
      * may be provided.
      *
+     * <p>
+     *     Note: do not pass in the full DER-encoded OCSPResponse object obtained from the responder,
+     *     only the DER-encoded BasicOCSPResponse value contained in the response data.
+     *
      * @param secondDigest the digest in the authenticatedAttributes
      * @param sigtype specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere: either basic CMS or CAdES
      * @param tsaClient    TSAClient - null or an optional time stamp authority client
-     * @param ocsp collection of DER-encoded OCSP responses for the  certificate in the signature certificates chain, or null if OCSP revocation data is not to be added.
-     * @param crlBytes collection of DER-encoded CRL for certificates from the signature certificates chain, or null if CRL revocation data is not to be added.
+     * @param ocsp collection of DER-encoded BasicOCSPResponses for the  certificate in the signature certificates
+     *             chain, or null if OCSP revocation data is not to be added.
+     * @param crlBytes collection of DER-encoded CRL for certificates from the signature certificates chain,
+     *                 or null if CRL revocation data is not to be added.
+     * @see <a href="https://datatracker.ietf.org/doc/html/rfc6960#section-4.2.1">RFC 6960 § 4.2.1</a>
      * @return byte[] the bytes for the PKCS7SignedData object
      */
     public byte[] getEncodedPKCS7(byte[] secondDigest, PdfSigner.CryptoStandard sigtype, ITSAClient tsaClient, Collection<byte[]> ocsp, Collection<byte[]> crlBytes) {
@@ -978,6 +993,12 @@ private ASN1EncodableVector buildUnauthenticatedAttributes(byte[] timeStampToken
      * The document digest is generated and put inside the attribute. The signing is done over the DER encoded
      * authenticatedAttributes. This method provides that encoding and the parameters must be
      * exactly the same as in {@link #getEncodedPKCS7(byte[])}.
+     *
+     * <p>
+     *     Note: do not pass in the full DER-encoded OCSPResponse object obtained from the responder,
+     *     only the DER-encoded BasicOCSPResponse value contained in the response data.
+     *
+     *
      * <p>
      * A simple example:
      * <pre>
@@ -997,10 +1018,14 @@ private ASN1EncodableVector buildUnauthenticatedAttributes(byte[] timeStampToken
      * </pre>
      *
      * @param secondDigest the content digest
-     * @param ocsp collection of DER-encoded OCSP responses for the  certificate in the signature certificates chain, or null if OCSP revocation data is not to be added.
-     * @param crlBytes collection of DER-encoded CRL for certificates from the signature certificates chain, or null if CRL revocation data is not to be added.
-     * @param sigtype specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere: either basic CMS or CAdES
+     * @param ocsp collection of DER-encoded BasicOCSPResponses for the  certificate in the signature certificates
+     *             chain, or null if OCSP revocation data is not to be added.
+     * @param crlBytes collection of DER-encoded CRL for certificates from the signature certificates chain,
+     *                 or null if CRL revocation data is not to be added.
+     * @param sigtype specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere:
+     *                either basic CMS or CAdES
      * @return the byte array representation of the authenticatedAttributes ready to be signed
+     * @see <a href="https://datatracker.ietf.org/doc/html/rfc6960#section-4.2.1">RFC 6960 § 4.2.1</a>
      * @deprecated This method overload is deprecated. Please use {@link #getAuthenticatedAttributeBytes(byte[], PdfSigner.CryptoStandard, Collection, Collection)}
      */
     @Deprecated
@@ -1013,6 +1038,11 @@ public byte[] getAuthenticatedAttributeBytes(byte[] secondDigest, byte[] ocsp, C
      * The document digest is generated and put inside the attribute. The signing is done over the DER encoded
      * authenticatedAttributes. This method provides that encoding and the parameters must be
      * exactly the same as in {@link #getEncodedPKCS7(byte[])}.
+     *
+     * <p>
+     *     Note: do not pass in the full DER-encoded OCSPResponse object obtained from the responder,
+     *     only the DER-encoded BasicOCSPResponse value contained in the response data.
+     *
      * <p>
      * A simple example:
      * <pre>
@@ -1032,10 +1062,14 @@ public byte[] getAuthenticatedAttributeBytes(byte[] secondDigest, byte[] ocsp, C
      * </pre>
      *
      * @param secondDigest the content digest
-     * @param sigtype specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere: either basic CMS or CAdES
-     * @param ocsp collection of DER-encoded OCSP responses for the  certificate in the signature certificates chain, or null if OCSP revocation data is not to be added.
-     * @param crlBytes collection of DER-encoded CRL for certificates from the signature certificates chain, or null if CRL revocation data is not to be added.
+     * @param sigtype specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere:
+     *                either basic CMS or CAdES
+     * @param ocsp collection of DER-encoded BasicOCSPResponses for the  certificate in the signature certificates
+     *             chain, or null if OCSP revocation data is not to be added.
+     * @param crlBytes collection of DER-encoded CRL for certificates from the signature certificates chain,
+     *                 or null if CRL revocation data is not to be added.
      * @return the byte array representation of the authenticatedAttributes ready to be signed
+     * @see <a href="https://datatracker.ietf.org/doc/html/rfc6960#section-4.2.1">RFC 6960 § 4.2.1</a>
      */
     public byte[] getAuthenticatedAttributeBytes(byte[] secondDigest, PdfSigner.CryptoStandard sigtype, Collection<byte[]> ocsp, Collection<byte[]> crlBytes) {
         try {