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

Autoported commit.
Original commit hash: [147f3f6e1]

Author: MatthiasValvekens

itext/itext.sign/itext/signatures/IOcspClient.cs

@@ -47,15 +47,26 @@ source product.
 namespace iText.Signatures {
     /// <summary>Interface for the Online Certificate Status Protocol (OCSP) Client.</summary>
     public interface IOcspClient {
-        /// <summary>Gets an encoded byte array with OCSP validation.</summary>
-        /// <remarks>Gets an encoded byte array with OCSP validation. The method should not throw an exception.</remarks>
+        /// <summary>Fetch a DER-encoded BasicOCSPResponse from an OCSP responder.</summary>
+        /// <remarks>
+        /// Fetch a DER-encoded BasicOCSPResponse from an OCSP responder. The method should not throw
+        /// an exception.
+        /// <para />
+        /// 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.
+        /// </remarks>
         /// <param name="checkCert">Certificate to check.</param>
         /// <param name="issuerCert">The parent certificate.</param>
         /// <param name="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
+        /// 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.
         /// </param>
-        /// <returns>A byte array with the validation or null if the validation could not be obtained</returns>
+        /// <returns>
+        /// a byte array containing a DER-encoded BasicOCSPResponse structure or null if one
+        /// could not be obtained
+        /// </returns>
+        /// <seealso><a href="https://datatracker.ietf.org/doc/html/rfc6960#section-4.2.1">RFC 6960 § 4.2.1</a></seealso>
         byte[] GetEncoded(X509Certificate checkCert, X509Certificate issuerCert, String url);
     }
 }

itext/itext.sign/itext/signatures/LtvVerification.cs

@@ -210,9 +210,9 @@ private X509Certificate GetParent(X509Certificate cert, X509Certificate[] certs)
 
         /// <summary>Adds verification to the signature.</summary>
         /// <param name="signatureName">name of the signature</param>
-        /// <param name="ocsps">collection of ocsp responses</param>
-        /// <param name="crls">collection of crls</param>
-        /// <param name="certs">collection of certificates</param>
+        /// <param name="ocsps">collection of DER-encoded BasicOCSPResponses</param>
+        /// <param name="crls">collection of DER-encoded CRLs</param>
+        /// <param name="certs">collection of DER-encoded certificates</param>
         /// <returns>boolean</returns>
         public virtual bool AddVerification(String signatureName, ICollection<byte[]> ocsps, ICollection<byte[]> crls
             , ICollection<byte[]> certs) {

itext/itext.sign/itext/signatures/OcspClientBouncyCastle.cs

@@ -101,15 +101,7 @@ public virtual BasicOcspResp GetBasicOCSPResp(X509Certificate checkCert, X509Cer
             return null;
         }
 
-        /// <summary>Gets an encoded byte array with OCSP validation.</summary>
-        /// <remarks>Gets an encoded byte array with OCSP validation. The method should not throw an exception.</remarks>
-        /// <param name="checkCert">to certificate to check</param>
-        /// <param name="rootCert">the parent certificate</param>
-        /// <param name="url">
-        /// to get the verification. It it's null it will be taken
-        /// from the check cert or from other implementation specific source
-        /// </param>
-        /// <returns>a byte array with the validation or null if the validation could not be obtained</returns>
+        /// <summary><inheritDoc/></summary>
         public virtual byte[] GetEncoded(X509Certificate checkCert, X509Certificate rootCert, String url) {
             try {
                 BasicOcspResp basicResponse = GetBasicOCSPResp(checkCert, rootCert, url);

itext/itext.sign/itext/signatures/PdfPKCS7.cs

@@ -664,16 +664,26 @@ public virtual byte[] GetEncodedPKCS7(byte[] secondDigest) {
         /// Gets the bytes for the PKCS7SignedData object. Optionally the authenticatedAttributes
         /// in the signerInfo can also be set, and/or a time-stamp-authority client
         /// may be provided.
+        /// <para />
+        /// 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.
         /// </remarks>
         /// <param name="secondDigest">the digest in the authenticatedAttributes</param>
         /// <param name="tsaClient">TSAClient - null or an optional time stamp authority client</param>
-        /// <param name="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>
-        /// <param name="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>
-        /// <param name="sigtype">specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere: either basic CMS or CAdES
-        ///     </param>
+        /// <param name="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>
+        /// <param name="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>
+        /// <param name="sigtype">
+        /// specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere:
+        /// either basic CMS or CAdES
+        /// </param>
         /// <returns>byte[] the bytes for the PKCS7SignedData object</returns>
+        /// <seealso><a href="https://datatracker.ietf.org/doc/html/rfc6960#section-4.2.1">RFC 6960 § 4.2.1</a></seealso>
         [System.ObsoleteAttribute(@"This overload is deprecated, use GetEncodedPKCS7(byte[], CryptoStandard, ITSAClient, System.Collections.Generic.ICollection{E}, System.Collections.Generic.ICollection{E}) instead."
             )]
         public virtual byte[] GetEncodedPKCS7(byte[] secondDigest, ITSAClient tsaClient, byte[] ocsp, ICollection<
@@ -687,15 +697,23 @@ public virtual byte[] GetEncodedPKCS7(byte[] secondDigest, ITSAClient tsaClient,
         /// Gets the bytes for the PKCS7SignedData object. Optionally the authenticatedAttributes
         /// in the signerInfo can also be set, and/or a time-stamp-authority client
         /// may be provided.
+        /// <para />
+        /// 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.
         /// </remarks>
         /// <param name="secondDigest">the digest in the authenticatedAttributes</param>
         /// <param name="sigtype">specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere: either basic CMS or CAdES
         ///     </param>
         /// <param name="tsaClient">TSAClient - null or an optional time stamp authority client</param>
-        /// <param name="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>
-        /// <param name="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>
+        /// <param name="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>
+        /// <param name="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>
+        /// <seealso><a href="https://datatracker.ietf.org/doc/html/rfc6960#section-4.2.1">RFC 6960 § 4.2.1</a></seealso>
         /// <returns>byte[] the bytes for the PKCS7SignedData object</returns>
         public virtual byte[] GetEncodedPKCS7(byte[] secondDigest, PdfSigner.CryptoStandard sigtype, ITSAClient tsaClient
             , ICollection<byte[]> ocsp, ICollection<byte[]> crlBytes) {
@@ -848,6 +866,9 @@ private Asn1EncodableVector BuildUnauthenticatedAttributes(byte[] timeStampToken
         /// exactly the same as in
         /// <see cref="GetEncodedPKCS7(byte[])"/>.
         /// <para />
+        /// 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.
+        /// <para />
         /// A simple example:
         /// <pre>
         /// Calendar cal = Calendar.getInstance();
@@ -866,13 +887,20 @@ private Asn1EncodableVector BuildUnauthenticatedAttributes(byte[] timeStampToken
         /// </pre>
         /// </remarks>
         /// <param name="secondDigest">the content digest</param>
-        /// <param name="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>
-        /// <param name="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>
-        /// <param name="sigtype">specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere: either basic CMS or CAdES
-        ///     </param>
+        /// <param name="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>
+        /// <param name="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>
+        /// <param name="sigtype">
+        /// specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere:
+        /// either basic CMS or CAdES
+        /// </param>
         /// <returns>the byte array representation of the authenticatedAttributes ready to be signed</returns>
+        /// <seealso><a href="https://datatracker.ietf.org/doc/html/rfc6960#section-4.2.1">RFC 6960 § 4.2.1</a></seealso>
         [System.ObsoleteAttribute(@"This method overload is deprecated. Please use GetAuthenticatedAttributeBytes(byte[], CryptoStandard, System.Collections.Generic.ICollection{E}, System.Collections.Generic.ICollection{E})"
             )]
         public virtual byte[] GetAuthenticatedAttributeBytes(byte[] secondDigest, byte[] ocsp, ICollection<byte[]>
@@ -889,6 +917,9 @@ public virtual byte[] GetAuthenticatedAttributeBytes(byte[] secondDigest, byte[]
         /// exactly the same as in
         /// <see cref="GetEncodedPKCS7(byte[])"/>.
         /// <para />
+        /// 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.
+        /// <para />
         /// A simple example:
         /// <pre>
         /// Calendar cal = Calendar.getInstance();
@@ -907,13 +938,20 @@ public virtual byte[] GetAuthenticatedAttributeBytes(byte[] secondDigest, byte[]
         /// </pre>
         /// </remarks>
         /// <param name="secondDigest">the content digest</param>
-        /// <param name="sigtype">specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere: either basic CMS or CAdES
-        ///     </param>
-        /// <param name="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>
-        /// <param name="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>
+        /// <param name="sigtype">
+        /// specifies the PKCS7 standard flavor to which created PKCS7SignedData object will adhere:
+        /// either basic CMS or CAdES
+        /// </param>
+        /// <param name="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>
+        /// <param name="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>
         /// <returns>the byte array representation of the authenticatedAttributes ready to be signed</returns>
+        /// <seealso><a href="https://datatracker.ietf.org/doc/html/rfc6960#section-4.2.1">RFC 6960 § 4.2.1</a></seealso>
         public virtual byte[] GetAuthenticatedAttributeBytes(byte[] secondDigest, PdfSigner.CryptoStandard sigtype
             , ICollection<byte[]> ocsp, ICollection<byte[]> crlBytes) {
             try {

port-hash

@@ -1 +1 @@
-377d5f5dd9988723b09077fcbc85c35a3df04f73 
+147f3f6e1532b9dc5244ec8156c5e4c75a191e08