docs: add XML documentation for CMS recipient info generators (Batch 16c)

crypto/src/cms/KEKRecipientInfoGenerator.cs

@@ -14,6 +14,10 @@
 
 namespace Org.BouncyCastle.Cms
 {
+    /// <summary>
+    /// Internal generator for CMS KEK <c>RecipientInfo</c> values. Configured and used by
+    /// <see cref="CmsEnvelopedGenerator.AddKekRecipient(string, KeyParameter, byte[])"/> and related overloads.
+    /// </summary>
     internal class KekRecipientInfoGenerator
 		: RecipientInfoGenerator
 	{
@@ -25,15 +29,18 @@ internal class KekRecipientInfoGenerator
 		// Derived
 		private AlgorithmIdentifier keyEncryptionAlgorithm;
 
+		/// <summary>Creates an unconfigured KEK recipient generator.</summary>
 		internal KekRecipientInfoGenerator()
 		{
 		}
 
+		/// <summary>Sets the KEK identifier carried in the generated RecipientInfo.</summary>
 		internal KekIdentifier KekIdentifier
 		{
 			set { this.kekIdentifier = value; }
 		}
 
+		/// <summary>Sets the key-encryption key and derives the wrap algorithm identifier.</summary>
 		internal KeyParameter KeyEncryptionKey
 		{
 			set
@@ -43,11 +50,16 @@ internal KeyParameter KeyEncryptionKey
 			}
 		}
 
+		/// <summary>Sets the base symmetric algorithm name used to select the CMS wrap OID.</summary>
 		internal string KeyEncryptionKeyOID
 		{
 			set { this.keyEncryptionKeyOID = value; }
 		}
 
+		/// <summary>Wraps <paramref name="contentEncryptionKey"/> with the configured KEK.</summary>
+		/// <param name="contentEncryptionKey">The content-encryption key to wrap.</param>
+		/// <param name="random">A source of randomness.</param>
+		/// <returns>A CMS RecipientInfo for KEK transport.</returns>
 		public RecipientInfo Generate(KeyParameter contentEncryptionKey, SecureRandom random)
 		{
 			byte[] keyBytes = contentEncryptionKey.GetKey();

crypto/src/cms/KeyAgreeRecipientInfoGenerator.cs

@@ -17,6 +17,10 @@
 
 namespace Org.BouncyCastle.Cms
 {
+    /// <summary>
+    /// Internal generator for CMS key-agreement <c>RecipientInfo</c> values. Configured and used by
+    /// <see cref="CmsEnvelopedGenerator"/> when adding key-agreement recipients.
+    /// </summary>
     internal class KeyAgreeRecipientInfoGenerator
         : RecipientInfoGenerator
     {
@@ -29,6 +33,8 @@ internal class KeyAgreeRecipientInfoGenerator
 
         private byte[] m_userKeyingMaterial;
 
+        /// <summary>Creates a generator for the given recipient certificates.</summary>
+        /// <param name="recipientCerts">The recipients' X.509 certificates.</param>
         internal KeyAgreeRecipientInfoGenerator(IEnumerable<X509Certificate> recipientCerts)
         {
             foreach (var recipientCert in recipientCerts)
@@ -38,33 +44,49 @@ internal KeyAgreeRecipientInfoGenerator(IEnumerable<X509Certificate> recipientCe
             }
         }
 
+        /// <summary>Creates a generator for a recipient identified by subject key identifier.</summary>
+        /// <param name="subjectKeyID">The recipient's subject key identifier.</param>
+        /// <param name="publicKey">The recipient's public key.</param>
         internal KeyAgreeRecipientInfoGenerator(byte[] subjectKeyID, AsymmetricKeyParameter publicKey)
         {
             m_recipientIDs.Add(new KeyAgreeRecipientIdentifier(new RecipientKeyIdentifier(subjectKeyID)));
             m_recipientKeys.Add(publicKey);
         }
 
+        /// <summary>Sets the key-agreement algorithm OID.</summary>
         internal DerObjectIdentifier KeyAgreementOid
         {
             set { m_keyAgreementOid = value; }
         }
 
+        /// <summary>Sets the key-encryption (wrap) algorithm OID.</summary>
         internal DerObjectIdentifier KeyEncryptionOid
         {
             set { m_keyEncryptionOid = value; }
         }
 
+        /// <summary>Sets the sender's static key-agreement key pair.</summary>
         internal AsymmetricCipherKeyPair SenderKeyPair
         {
             set { m_senderKeyPair = value; }
         }
 
         // TODO[cms] Support public configuration of this
+        /// <summary>Sets optional user keying material for the agreement algorithm.</summary>
         internal byte[] UserKeyingMaterial
         {
             set { m_userKeyingMaterial = Arrays.Clone(value); }
         }
 
+        /// <summary>
+        /// Derives per-recipient wrap keys and returns a key-agreement RecipientInfo for
+        /// <paramref name="contentEncryptionKey"/>.
+        /// </summary>
+        /// <param name="contentEncryptionKey">The content-encryption key to protect for each recipient.</param>
+        /// <param name="random">A source of randomness.</param>
+        /// <returns>A CMS RecipientInfo for key agreement.</returns>
+        /// <exception cref="InvalidKeyException">The sender or recipient keys cannot be used for agreement.</exception>
+        /// <exception cref="CmsException">No recipients are associated with this generator.</exception>
         public RecipientInfo Generate(KeyParameter contentEncryptionKey, SecureRandom random)
         {
             random = CryptoServicesRegistrar.GetSecureRandom(random);

crypto/src/cms/KeyTransRecipientInfoGenerator.cs

@@ -8,6 +8,11 @@
 
 namespace Org.BouncyCastle.Cms
 {
+    /// <summary>
+    /// Generates CMS key-transport <c>RecipientInfo</c> values. Used by
+    /// <see cref="CmsEnvelopedGenerator.AddKeyTransRecipient(X509Certificate)"/> and related overloads; the read-side
+    /// counterpart is <see cref="KeyTransRecipientInformation"/>.
+    /// </summary>
     public class KeyTransRecipientInfoGenerator
         : RecipientInfoGenerator
     {
@@ -16,23 +21,36 @@ public class KeyTransRecipientInfoGenerator
         private IssuerAndSerialNumber m_issuerAndSerialNumber;
         private SubjectKeyIdentifier m_subjectKeyIdentifier;
 
+        /// <summary>Creates a generator that identifies the recipient from an X.509 certificate.</summary>
+        /// <param name="recipCert">The recipient's public-key certificate.</param>
+        /// <param name="keyWrapper">The key wrapper used to encrypt the content-encryption key.</param>
         public KeyTransRecipientInfoGenerator(X509Certificate recipCert, IKeyWrapper keyWrapper)
             : this(new IssuerAndSerialNumber(recipCert.CertificateStructure), keyWrapper)
         {
         }
 
+        /// <summary>Creates a generator that identifies the recipient by issuer and serial number.</summary>
+        /// <param name="issuerAndSerial">The recipient's issuer and serial number.</param>
+        /// <param name="keyWrapper">The key wrapper used to encrypt the content-encryption key.</param>
         public KeyTransRecipientInfoGenerator(IssuerAndSerialNumber issuerAndSerial, IKeyWrapper keyWrapper)
         {
             m_issuerAndSerialNumber = issuerAndSerial;
             m_keyWrapper = keyWrapper;
         }
 
+        /// <summary>Creates a generator that identifies the recipient by subject key identifier.</summary>
+        /// <param name="subjectKeyID">The recipient's subject key identifier.</param>
+        /// <param name="keyWrapper">The key wrapper used to encrypt the content-encryption key.</param>
         public KeyTransRecipientInfoGenerator(byte[] subjectKeyID, IKeyWrapper keyWrapper)
         {
             m_subjectKeyIdentifier = new SubjectKeyIdentifier(subjectKeyID);
             m_keyWrapper = keyWrapper;
         }
 
+        /// <summary>Wraps <paramref name="contentEncryptionKey"/> and returns a key-transport RecipientInfo.</summary>
+        /// <param name="contentEncryptionKey">The content-encryption key to wrap for the recipient.</param>
+        /// <param name="random">A source of randomness (not used directly by this generator).</param>
+        /// <returns>A CMS RecipientInfo for key transport.</returns>
         public RecipientInfo Generate(KeyParameter contentEncryptionKey, SecureRandom random)
         {
             AlgorithmIdentifier keyEncryptionAlgorithm = AlgorithmDetails;
@@ -53,11 +71,15 @@ public RecipientInfo Generate(KeyParameter contentEncryptionKey, SecureRandom ra
                 new DerOctetString(encryptedKeyBytes)));
         }
 
+        /// <summary>Gets the key-encryption algorithm identifier from the key wrapper.</summary>
         protected virtual AlgorithmIdentifier AlgorithmDetails
         {
             get { return (AlgorithmIdentifier)m_keyWrapper.AlgorithmDetails; }
         }
 
+        /// <summary>Wraps the content-encryption key using the configured key wrapper.</summary>
+        /// <param name="contentEncryptionKey">The content-encryption key to wrap.</param>
+        /// <returns>The wrapped key bytes.</returns>
         protected virtual byte[] GenerateWrappedKey(KeyParameter contentEncryptionKey)
         {
             return m_keyWrapper.Wrap(contentEncryptionKey.GetKey()).Collect();

crypto/src/cms/PasswordRecipientInfoGenerator.cs

@@ -11,6 +11,10 @@
 
 namespace Org.BouncyCastle.Cms
 {
+	/// <summary>
+	/// Internal generator for CMS password-based <c>RecipientInfo</c> values. Configured and used by
+	/// <see cref="CmsEnvelopedGenerator.AddPasswordRecipient(CmsPbeKey, string)"/>.
+	/// </summary>
 	internal class PasswordRecipientInfoGenerator
 		: RecipientInfoGenerator
 	{
@@ -19,25 +23,33 @@ internal class PasswordRecipientInfoGenerator
 		// TODO Can get this from keyEncryptionKey?		
 		private string				keyEncryptionKeyOID;
 
+		/// <summary>Creates an unconfigured password recipient generator.</summary>
 		internal PasswordRecipientInfoGenerator()
 		{
 		}
 
+		/// <summary>Sets the key-derivation algorithm for the password recipient.</summary>
 		internal AlgorithmIdentifier KeyDerivationAlgorithm
 		{
 			set { this.keyDerivationAlgorithm = value; }
 		}
 
+		/// <summary>Sets the key-encryption key derived from the password.</summary>
 		internal KeyParameter KeyEncryptionKey
 		{
 			set { this.keyEncryptionKey = value; }
 		}
 
+		/// <summary>Sets the symmetric algorithm OID used for RFC 3211 key wrapping.</summary>
 		internal string KeyEncryptionKeyOID
 		{
 			set { this.keyEncryptionKeyOID = value; }
 		}
 
+		/// <summary>Wraps <paramref name="contentEncryptionKey"/> using the configured password-derived KEK.</summary>
+		/// <param name="contentEncryptionKey">The content-encryption key to wrap.</param>
+		/// <param name="random">A source of randomness used for the RFC 3211 IV.</param>
+		/// <returns>A CMS RecipientInfo for password-based key management.</returns>
 		public RecipientInfo Generate(KeyParameter contentEncryptionKey, SecureRandom random)
 		{
 			byte[] keyBytes = contentEncryptionKey.GetKey();