docs: add XML documentation for CMS exceptions and PBE keys (Batch 16e)

crypto/src/cms/CMSAttributeTableGenerationException.cs

@@ -3,6 +3,7 @@
 
 namespace Org.BouncyCastle.Cms
 {
+    /// <summary>Exception thrown when a CMS signed or authenticated attribute table cannot be generated.</summary>
     [Serializable]
     public class CmsAttributeTableGenerationException
         : CmsException

crypto/src/cms/CMSException.cs

@@ -3,6 +3,7 @@
 
 namespace Org.BouncyCastle.Cms
 {
+    /// <summary>General exception thrown when CMS processing fails.</summary>
     [Serializable]
     public class CmsException
         : Exception

crypto/src/cms/CMSPBEKey.cs

@@ -11,6 +11,10 @@
 
 namespace Org.BouncyCastle.Cms
 {
+	/// <summary>
+	/// Base class for password-based keys used with CMS enveloped-data recipients. Passed to
+	/// <see cref="CmsEnvelopedGenerator.AddPasswordRecipient"/>.
+	/// </summary>
 	public abstract class CmsPbeKey
 		// TODO Create an equivalent interface somewhere?
 		//	: PBEKey
@@ -20,6 +24,10 @@ public abstract class CmsPbeKey
 		internal readonly byte[]	salt;
 		internal readonly int		iterationCount;
 
+		/// <summary>Creates a PBE key from explicit password, salt, and iteration count.</summary>
+		/// <param name="password">The password characters.</param>
+		/// <param name="salt">The PBKDF2 salt.</param>
+		/// <param name="iterationCount">The PBKDF2 iteration count.</param>
 		public CmsPbeKey(
 			char[]	password,
 			byte[]	salt,
@@ -30,6 +38,10 @@ public CmsPbeKey(
 			this.iterationCount = iterationCount;
 		}
 
+		/// <summary>Creates a PBE key from a password and PBKDF2 AlgorithmIdentifier.</summary>
+		/// <param name="password">The password characters.</param>
+		/// <param name="keyDerivationAlgorithm">The PBKDF2 algorithm identifier.</param>
+		/// <exception cref="ArgumentException">The key derivation algorithm is not PBKDF2.</exception>
 		public CmsPbeKey(
 			char[]				password,
 			AlgorithmIdentifier keyDerivationAlgorithm)
@@ -49,13 +61,16 @@ public CmsPbeKey(
 		}
 
 #if NETCOREAPP2_1_OR_GREATER || NETSTANDARD2_1_OR_GREATER
+        /// <summary>Creates a PBE key from explicit password, salt, and iteration count.</summary>
         public CmsPbeKey(ReadOnlySpan<char> password, ReadOnlySpan<byte> salt, int iterationCount)
         {
 			this.password = password.ToArray();
 			this.salt = salt.ToArray();
             this.iterationCount = iterationCount;
         }
 
+        /// <summary>Creates a PBE key from a password and PBKDF2 AlgorithmIdentifier.</summary>
+        /// <exception cref="ArgumentException">The key derivation algorithm is not PBKDF2.</exception>
         public CmsPbeKey(ReadOnlySpan<char> password, AlgorithmIdentifier keyDerivationAlgorithm)
         {
             if (!keyDerivationAlgorithm.Algorithm.Equals(PkcsObjectIdentifiers.IdPbkdf2))
@@ -79,26 +94,32 @@ public CmsPbeKey(ReadOnlySpan<char> password, AlgorithmIdentifier keyDerivationA
 			Arrays.ZeroMemory(this.password);
 		}
 
+		/// <summary>Gets a copy of the PBKDF2 salt.</summary>
 		public byte[] Salt
 		{
 			get { return Arrays.Clone(salt); }
 		}
 
+		/// <summary>Gets the PBKDF2 iteration count.</summary>
 		public int IterationCount
 		{
 			get { return iterationCount; }
 		}
 
+		/// <summary>Gets the key algorithm name (<c>PKCS5S2</c>).</summary>
 		public string Algorithm
 		{
 			get { return "PKCS5S2"; }
 		}
 
+		/// <summary>Gets the encoding format name (<c>RAW</c>).</summary>
 		public string Format
 		{
 			get { return "RAW"; }
 		}
 
+		/// <summary>Returns null; raw encoding is not supported.</summary>
+		/// <returns>Always null.</returns>
 		public byte[] GetEncoded()
 		{
 			return null;

crypto/src/cms/CMSStreamException.cs

@@ -4,6 +4,7 @@
 
 namespace Org.BouncyCastle.Cms
 {
+    /// <summary>Exception thrown when CMS streaming operations fail.</summary>
     [Serializable]
     public class CmsStreamException
         : IOException

crypto/src/cms/CmsAlgorithmNotAllowedException.cs

@@ -3,6 +3,7 @@
 
 namespace Org.BouncyCastle.Cms
 {
+    /// <summary>Exception thrown when a CMS operation does not permit the requested algorithm.</summary>
     [Serializable]
     public class CmsAlgorithmNotAllowedException
         : CmsException

crypto/src/cms/CmsTagLengthException.cs

@@ -3,6 +3,7 @@
 
 namespace Org.BouncyCastle.Cms
 {
+    /// <summary>Exception thrown when an authenticated CMS content tag length is invalid.</summary>
     [Serializable]
     public class CmsTagLengthException
         : CmsException

crypto/src/cms/CmsVerifierCertificateNotValidException.cs

@@ -3,6 +3,7 @@
 
 namespace Org.BouncyCastle.Cms
 {
+    /// <summary>Exception thrown when a signer certificate is not valid at the signing time.</summary>
     [Serializable]
     public class CmsVerifierCertificateNotValidException
         : CmsException

crypto/src/cms/PKCS5Scheme2PBEKey.cs

@@ -8,12 +8,11 @@
 
 namespace Org.BouncyCastle.Cms
 {
-	/// <summary>
-	/// PKCS5 scheme-2 - password converted to bytes assuming ASCII.
-	/// </summary>
+	/// <summary>PKCS#5 scheme 2 PBE key with the password encoded as ASCII bytes.</summary>
 	public class Pkcs5Scheme2PbeKey
 		: CmsPbeKey
 	{
+		/// <inheritdoc/>
 		public Pkcs5Scheme2PbeKey(
 			char[]	password,
 			byte[]	salt,
@@ -22,6 +21,7 @@ public Pkcs5Scheme2PbeKey(
 		{
 		}
 
+		/// <inheritdoc/>
 		public Pkcs5Scheme2PbeKey(
 			char[]				password,
 			AlgorithmIdentifier keyDerivationAlgorithm)
@@ -30,11 +30,13 @@ public Pkcs5Scheme2PbeKey(
 		}
 
 #if NETCOREAPP2_1_OR_GREATER || NETSTANDARD2_1_OR_GREATER
+        /// <inheritdoc/>
         public Pkcs5Scheme2PbeKey(ReadOnlySpan<char> password, ReadOnlySpan<byte> salt, int iterationCount)
             : base(password, salt, iterationCount)
         {
         }
 
+        /// <inheritdoc/>
         public Pkcs5Scheme2PbeKey(ReadOnlySpan<char> password, AlgorithmIdentifier keyDerivationAlgorithm)
             : base(password, keyDerivationAlgorithm)
         {

crypto/src/cms/PKCS5Scheme2UTF8PBEKey.cs

@@ -8,12 +8,11 @@
 
 namespace Org.BouncyCastle.Cms
 {
-	/**
-	 * PKCS5 scheme-2 - password converted to bytes using UTF-8.
-	 */
+	/// <summary>PKCS#5 scheme 2 PBE key with the password encoded as UTF-8 bytes.</summary>
 	public class Pkcs5Scheme2Utf8PbeKey
 		: CmsPbeKey
 	{
+		/// <inheritdoc/>
 		public Pkcs5Scheme2Utf8PbeKey(
 			char[]	password,
 			byte[]	salt,
@@ -22,6 +21,7 @@ public Pkcs5Scheme2Utf8PbeKey(
 		{
 		}
 
+		/// <inheritdoc/>
 		public Pkcs5Scheme2Utf8PbeKey(
 			char[]				password,
 			AlgorithmIdentifier keyDerivationAlgorithm)
@@ -30,11 +30,13 @@ public Pkcs5Scheme2Utf8PbeKey(
 		}
 
 #if NETCOREAPP2_1_OR_GREATER || NETSTANDARD2_1_OR_GREATER
+        /// <inheritdoc/>
         public Pkcs5Scheme2Utf8PbeKey(ReadOnlySpan<char> password, ReadOnlySpan<byte> salt, int iterationCount)
             : base(password, salt, iterationCount)
         {
         }
 
+        /// <inheritdoc/>
         public Pkcs5Scheme2Utf8PbeKey(ReadOnlySpan<char> password, AlgorithmIdentifier keyDerivationAlgorithm)
             : base(password, keyDerivationAlgorithm)
         {