diff --git a/crypto/src/cms/KEKRecipientInformation.cs b/crypto/src/cms/KEKRecipientInformation.cs index 649760103..c8e1b8bf5 100644 --- a/crypto/src/cms/KEKRecipientInformation.cs +++ b/crypto/src/cms/KEKRecipientInformation.cs @@ -9,54 +9,54 @@ namespace Org.BouncyCastle.Cms { - /** - * the RecipientInfo class for a recipient who has been sent a message - * encrypted using a secret key known to the other side. - */ + /// + /// CMS recipient information for key-encryption-key (KEK) recipients that share a symmetric wrapping key. + /// public class KekRecipientInformation : RecipientInformation { private KekRecipientInfo info; - internal KekRecipientInformation( - KekRecipientInfo info, - CmsSecureReadable secureReadable) - : base(info.KeyEncryptionAlgorithm, secureReadable) - { + internal KekRecipientInformation( + KekRecipientInfo info, + CmsSecureReadable secureReadable) + : base(info.KeyEncryptionAlgorithm, secureReadable) + { this.info = info; this.rid = new RecipientID(); - KekIdentifier kekId = info.KekID; + KekIdentifier kekId = info.KekID; - rid.KeyIdentifier = kekId.KeyIdentifier.GetOctets(); + rid.KeyIdentifier = kekId.KeyIdentifier.GetOctets(); } - /** - * decrypt the content and return an input stream. - */ + /// Decrypts the content using the recipient's shared key-encryption key. + /// The shared key-encryption key. + /// A typed stream over the decrypted content. + /// Thrown if the content-encryption key cannot be recovered. public override CmsTypedStream GetContentStream( ICipherParameters key) { - try - { - byte[] encryptedKey = info.EncryptedKey.GetOctets(); + try + { + byte[] encryptedKey = info.EncryptedKey.GetOctets(); IWrapper keyWrapper = WrapperUtilities.GetWrapper(keyEncAlg.Algorithm); - keyWrapper.Init(false, key); - - KeyParameter sKey = ParameterUtilities.CreateKeyParameter( - GetContentAlgorithmName(), keyWrapper.Unwrap(encryptedKey, 0, encryptedKey.Length)); - - return GetContentFromSessionKey(sKey); - } - catch (SecurityUtilityException e) - { - throw new CmsException("couldn't create cipher.", e); - } - catch (InvalidKeyException e) - { - throw new CmsException("key invalid in message.", e); - } + keyWrapper.Init(false, key); + + KeyParameter sKey = ParameterUtilities.CreateKeyParameter( + GetContentAlgorithmName(), keyWrapper.Unwrap(encryptedKey, 0, encryptedKey.Length)); + + return GetContentFromSessionKey(sKey); + } + catch (SecurityUtilityException e) + { + throw new CmsException("couldn't create cipher.", e); + } + catch (InvalidKeyException e) + { + throw new CmsException("key invalid in message.", e); + } } } } diff --git a/crypto/src/cms/KeyAgreeRecipientInformation.cs b/crypto/src/cms/KeyAgreeRecipientInformation.cs index 85be5199a..107305022 100644 --- a/crypto/src/cms/KeyAgreeRecipientInformation.cs +++ b/crypto/src/cms/KeyAgreeRecipientInformation.cs @@ -17,10 +17,9 @@ namespace Org.BouncyCastle.Cms { - /** - * the RecipientInfo class for a recipient who has been sent a message - * encrypted using key agreement. - */ + /// + /// CMS recipient information for key agreement, where a sender and recipient derive the key-encryption key. + /// public class KeyAgreeRecipientInformation : RecipientInformation { @@ -197,9 +196,12 @@ internal KeyParameter GetSessionKey(AsymmetricKeyParameter receiverPrivateKey) } } - /** - * decrypt the content and return an input stream. - */ + /// Decrypts the content using the recipient's key-agreement private key. + /// The recipient's private asymmetric key. + /// A typed stream over the decrypted content. + /// Thrown if is not a private asymmetric key. + /// + /// Thrown if key agreement or content-key recovery fails. public override CmsTypedStream GetContentStream( ICipherParameters key) { diff --git a/crypto/src/cms/KeyTransRecipientInformation.cs b/crypto/src/cms/KeyTransRecipientInformation.cs index 06ae0921e..58371099a 100644 --- a/crypto/src/cms/KeyTransRecipientInformation.cs +++ b/crypto/src/cms/KeyTransRecipientInformation.cs @@ -13,11 +13,10 @@ namespace Org.BouncyCastle.Cms { - /** - * the KeyTransRecipientInformation class for a recipient who has been sent a secret - * key encrypted using their public key that needs to be used to - * extract the message. - */ + /// + /// CMS recipient information for key transport, where the content-encryption key is encrypted for a recipient's + /// public key. + /// public class KeyTransRecipientInformation : RecipientInformation { @@ -142,7 +141,10 @@ internal KeyParameter UnwrapKey(ICipherParameters key) } } - /// Decrypt the content and return it as a byte array. + /// Decrypts the content using the recipient's private key and returns a stream over it. + /// The recipient's private key. + /// A typed stream over the decrypted content. + /// Thrown if the content-encryption key cannot be recovered. public override CmsTypedStream GetContentStream(ICipherParameters key) => GetContentFromSessionKey(UnwrapKey(key)); } } diff --git a/crypto/src/cms/PasswordRecipientInformation.cs b/crypto/src/cms/PasswordRecipientInformation.cs index dbdc46a96..679efaded 100644 --- a/crypto/src/cms/PasswordRecipientInformation.cs +++ b/crypto/src/cms/PasswordRecipientInformation.cs @@ -9,7 +9,7 @@ namespace Org.BouncyCastle.Cms { - /// The RecipientInfo class for a recipient who has been sent a message encrypted using a password. + /// CMS recipient information for a recipient that recovers content using a password-derived key. public class PasswordRecipientInformation : RecipientInformation { @@ -22,12 +22,13 @@ internal PasswordRecipientInformation(PasswordRecipientInfo info, CmsSecureReada this.rid = new RecipientID(); } - /// - /// Return the object identifier for the key derivation algorithm, or null if there is none present. - /// + /// Gets the key-derivation algorithm, or null when the message does not include one. public virtual AlgorithmIdentifier KeyDerivationAlgorithm => m_info.KeyDerivationAlgorithm; - /// Decrypt the content and return an input stream. + /// Decrypts the content using a password-based recipient key. + /// The password-based recipient key. + /// A typed stream over the decrypted content. + /// Thrown if the content-encryption key cannot be recovered. public override CmsTypedStream GetContentStream(ICipherParameters key) { try diff --git a/crypto/src/cms/RecipientId.cs b/crypto/src/cms/RecipientId.cs index c4107b14e..acdf60222 100644 --- a/crypto/src/cms/RecipientId.cs +++ b/crypto/src/cms/RecipientId.cs @@ -5,18 +5,26 @@ namespace Org.BouncyCastle.Cms { + /// + /// Identifies a CMS recipient by issuer and serial number, subject key identifier, or KEK key identifier. + /// // TODO[api] sealed public class RecipientID : X509CertStoreSelector, IEquatable { private byte[] m_keyIdentifier; - public byte[] KeyIdentifier - { - get { return Arrays.Clone(m_keyIdentifier); } - set { m_keyIdentifier = Arrays.Clone(value); } - } + /// Gets or sets the recipient key identifier. + public byte[] KeyIdentifier + { + get { return Arrays.Clone(m_keyIdentifier); } + set { m_keyIdentifier = Arrays.Clone(value); } + } + /// Determines whether this identifier selects the same recipient as . + /// + /// The identifier to compare. + /// true if the identifiers match; otherwise, false. public virtual bool Equals(RecipientID other) { return other == null ? false @@ -27,12 +35,14 @@ public virtual bool Equals(RecipientID other) && MatchesIssuer(other); } + /// public override bool Equals(object obj) => Equals(obj as RecipientID); + /// public override int GetHashCode() { return Arrays.GetHashCode(m_keyIdentifier) - ^ GetHashCodeOfSubjectKeyIdentifier() + ^ GetHashCodeOfSubjectKeyIdentifier() ^ Objects.GetHashCode(SerialNumber) ^ Objects.GetHashCode(Issuer); } diff --git a/crypto/src/cms/RecipientInformation.cs b/crypto/src/cms/RecipientInformation.cs index 847008a7f..e5d1aef4d 100644 --- a/crypto/src/cms/RecipientInformation.cs +++ b/crypto/src/cms/RecipientInformation.cs @@ -10,6 +10,10 @@ namespace Org.BouncyCastle.Cms { + /// + /// Base class for CMS recipient information. Use to select a recipient, then supply + /// the matching key material to or . + /// public abstract class RecipientInformation { internal RecipientID rid = new RecipientID(); @@ -31,8 +35,10 @@ internal string GetContentAlgorithmName() return algorithm.Algorithm.Id; } + /// Gets the identifier used to match this recipient. public RecipientID RecipientID => rid; + /// Gets the algorithm identifier used to encrypt or wrap the content-encryption key. public AlgorithmIdentifier KeyEncryptionAlgorithmID => keyEncAlg; /// Return the object identifier for the key encryption algorithm. @@ -57,6 +63,9 @@ internal CmsTypedStream GetContentFromSessionKey(KeyParameter sKey) } } + /// Decrypts the content using and returns all of its bytes. + /// The recipient key material needed to recover the content-encryption key. + /// The decrypted or authenticated content. public byte[] GetContent(ICipherParameters key) { try @@ -87,6 +96,9 @@ public byte[] GetMac() return Arrays.Clone(resultMac); } + /// Returns a stream that exposes the recovered content. + /// The recipient key material needed to recover the content-encryption key. + /// A typed stream over the recovered content. public abstract CmsTypedStream GetContentStream(ICipherParameters key); } }