diff --git a/crypto/src/cms/KEKRecipientInfoGenerator.cs b/crypto/src/cms/KEKRecipientInfoGenerator.cs index 3846d6e36..2eb023f54 100644 --- a/crypto/src/cms/KEKRecipientInfoGenerator.cs +++ b/crypto/src/cms/KEKRecipientInfoGenerator.cs @@ -14,6 +14,10 @@ namespace Org.BouncyCastle.Cms { + /// + /// Internal generator for CMS KEK RecipientInfo values. Configured and used by + /// and related overloads. + /// internal class KekRecipientInfoGenerator : RecipientInfoGenerator { @@ -25,15 +29,18 @@ internal class KekRecipientInfoGenerator // Derived private AlgorithmIdentifier keyEncryptionAlgorithm; + /// Creates an unconfigured KEK recipient generator. internal KekRecipientInfoGenerator() { } + /// Sets the KEK identifier carried in the generated RecipientInfo. internal KekIdentifier KekIdentifier { set { this.kekIdentifier = value; } } + /// Sets the key-encryption key and derives the wrap algorithm identifier. internal KeyParameter KeyEncryptionKey { set @@ -43,11 +50,16 @@ internal KeyParameter KeyEncryptionKey } } + /// Sets the base symmetric algorithm name used to select the CMS wrap OID. internal string KeyEncryptionKeyOID { set { this.keyEncryptionKeyOID = value; } } + /// Wraps with the configured KEK. + /// The content-encryption key to wrap. + /// A source of randomness. + /// A CMS RecipientInfo for KEK transport. public RecipientInfo Generate(KeyParameter contentEncryptionKey, SecureRandom random) { byte[] keyBytes = contentEncryptionKey.GetKey(); diff --git a/crypto/src/cms/KeyAgreeRecipientInfoGenerator.cs b/crypto/src/cms/KeyAgreeRecipientInfoGenerator.cs index 63283d283..10a2db376 100644 --- a/crypto/src/cms/KeyAgreeRecipientInfoGenerator.cs +++ b/crypto/src/cms/KeyAgreeRecipientInfoGenerator.cs @@ -17,6 +17,10 @@ namespace Org.BouncyCastle.Cms { + /// + /// Internal generator for CMS key-agreement RecipientInfo values. Configured and used by + /// when adding key-agreement recipients. + /// internal class KeyAgreeRecipientInfoGenerator : RecipientInfoGenerator { @@ -29,6 +33,8 @@ internal class KeyAgreeRecipientInfoGenerator private byte[] m_userKeyingMaterial; + /// Creates a generator for the given recipient certificates. + /// The recipients' X.509 certificates. internal KeyAgreeRecipientInfoGenerator(IEnumerable recipientCerts) { foreach (var recipientCert in recipientCerts) @@ -38,33 +44,49 @@ internal KeyAgreeRecipientInfoGenerator(IEnumerable recipientCe } } + /// Creates a generator for a recipient identified by subject key identifier. + /// The recipient's subject key identifier. + /// The recipient's public key. internal KeyAgreeRecipientInfoGenerator(byte[] subjectKeyID, AsymmetricKeyParameter publicKey) { m_recipientIDs.Add(new KeyAgreeRecipientIdentifier(new RecipientKeyIdentifier(subjectKeyID))); m_recipientKeys.Add(publicKey); } + /// Sets the key-agreement algorithm OID. internal DerObjectIdentifier KeyAgreementOid { set { m_keyAgreementOid = value; } } + /// Sets the key-encryption (wrap) algorithm OID. internal DerObjectIdentifier KeyEncryptionOid { set { m_keyEncryptionOid = value; } } + /// Sets the sender's static key-agreement key pair. internal AsymmetricCipherKeyPair SenderKeyPair { set { m_senderKeyPair = value; } } // TODO[cms] Support public configuration of this + /// Sets optional user keying material for the agreement algorithm. internal byte[] UserKeyingMaterial { set { m_userKeyingMaterial = Arrays.Clone(value); } } + /// + /// Derives per-recipient wrap keys and returns a key-agreement RecipientInfo for + /// . + /// + /// The content-encryption key to protect for each recipient. + /// A source of randomness. + /// A CMS RecipientInfo for key agreement. + /// The sender or recipient keys cannot be used for agreement. + /// No recipients are associated with this generator. public RecipientInfo Generate(KeyParameter contentEncryptionKey, SecureRandom random) { random = CryptoServicesRegistrar.GetSecureRandom(random); diff --git a/crypto/src/cms/KeyTransRecipientInfoGenerator.cs b/crypto/src/cms/KeyTransRecipientInfoGenerator.cs index 13bc184e2..36cbc8e62 100644 --- a/crypto/src/cms/KeyTransRecipientInfoGenerator.cs +++ b/crypto/src/cms/KeyTransRecipientInfoGenerator.cs @@ -8,6 +8,11 @@ namespace Org.BouncyCastle.Cms { + /// + /// Generates CMS key-transport RecipientInfo values. Used by + /// and related overloads; the read-side + /// counterpart is . + /// public class KeyTransRecipientInfoGenerator : RecipientInfoGenerator { @@ -16,23 +21,36 @@ public class KeyTransRecipientInfoGenerator private IssuerAndSerialNumber m_issuerAndSerialNumber; private SubjectKeyIdentifier m_subjectKeyIdentifier; + /// Creates a generator that identifies the recipient from an X.509 certificate. + /// The recipient's public-key certificate. + /// The key wrapper used to encrypt the content-encryption key. public KeyTransRecipientInfoGenerator(X509Certificate recipCert, IKeyWrapper keyWrapper) : this(new IssuerAndSerialNumber(recipCert.CertificateStructure), keyWrapper) { } + /// Creates a generator that identifies the recipient by issuer and serial number. + /// The recipient's issuer and serial number. + /// The key wrapper used to encrypt the content-encryption key. public KeyTransRecipientInfoGenerator(IssuerAndSerialNumber issuerAndSerial, IKeyWrapper keyWrapper) { m_issuerAndSerialNumber = issuerAndSerial; m_keyWrapper = keyWrapper; } + /// Creates a generator that identifies the recipient by subject key identifier. + /// The recipient's subject key identifier. + /// The key wrapper used to encrypt the content-encryption key. public KeyTransRecipientInfoGenerator(byte[] subjectKeyID, IKeyWrapper keyWrapper) { m_subjectKeyIdentifier = new SubjectKeyIdentifier(subjectKeyID); m_keyWrapper = keyWrapper; } + /// Wraps and returns a key-transport RecipientInfo. + /// The content-encryption key to wrap for the recipient. + /// A source of randomness (not used directly by this generator). + /// A CMS RecipientInfo for key transport. public RecipientInfo Generate(KeyParameter contentEncryptionKey, SecureRandom random) { AlgorithmIdentifier keyEncryptionAlgorithm = AlgorithmDetails; @@ -53,11 +71,15 @@ public RecipientInfo Generate(KeyParameter contentEncryptionKey, SecureRandom ra new DerOctetString(encryptedKeyBytes))); } + /// Gets the key-encryption algorithm identifier from the key wrapper. protected virtual AlgorithmIdentifier AlgorithmDetails { get { return (AlgorithmIdentifier)m_keyWrapper.AlgorithmDetails; } } + /// Wraps the content-encryption key using the configured key wrapper. + /// The content-encryption key to wrap. + /// The wrapped key bytes. protected virtual byte[] GenerateWrappedKey(KeyParameter contentEncryptionKey) { return m_keyWrapper.Wrap(contentEncryptionKey.GetKey()).Collect(); diff --git a/crypto/src/cms/PasswordRecipientInfoGenerator.cs b/crypto/src/cms/PasswordRecipientInfoGenerator.cs index 753ca6a39..bf89601d6 100644 --- a/crypto/src/cms/PasswordRecipientInfoGenerator.cs +++ b/crypto/src/cms/PasswordRecipientInfoGenerator.cs @@ -11,6 +11,10 @@ namespace Org.BouncyCastle.Cms { + /// + /// Internal generator for CMS password-based RecipientInfo values. Configured and used by + /// . + /// internal class PasswordRecipientInfoGenerator : RecipientInfoGenerator { @@ -19,25 +23,33 @@ internal class PasswordRecipientInfoGenerator // TODO Can get this from keyEncryptionKey? private string keyEncryptionKeyOID; + /// Creates an unconfigured password recipient generator. internal PasswordRecipientInfoGenerator() { } + /// Sets the key-derivation algorithm for the password recipient. internal AlgorithmIdentifier KeyDerivationAlgorithm { set { this.keyDerivationAlgorithm = value; } } + /// Sets the key-encryption key derived from the password. internal KeyParameter KeyEncryptionKey { set { this.keyEncryptionKey = value; } } + /// Sets the symmetric algorithm OID used for RFC 3211 key wrapping. internal string KeyEncryptionKeyOID { set { this.keyEncryptionKeyOID = value; } } + /// Wraps using the configured password-derived KEK. + /// The content-encryption key to wrap. + /// A source of randomness used for the RFC 3211 IV. + /// A CMS RecipientInfo for password-based key management. public RecipientInfo Generate(KeyParameter contentEncryptionKey, SecureRandom random) { byte[] keyBytes = contentEncryptionKey.GetKey();