From 716a8d4abecd667f47f348bbcd900801ef8a8bc6 Mon Sep 17 00:00:00 2001 From: Konradsop Date: Fri, 4 Sep 2026 07:53:09 +0200 Subject: [PATCH] Add XML documentation for CMS exceptions and PBE keys --- .../CMSAttributeTableGenerationException.cs | 1 + crypto/src/cms/CMSException.cs | 1 + crypto/src/cms/CMSPBEKey.cs | 21 +++++++++++++++++++ crypto/src/cms/CMSStreamException.cs | 1 + .../cms/CmsAlgorithmNotAllowedException.cs | 1 + crypto/src/cms/CmsTagLengthException.cs | 1 + ...CmsVerifierCertificateNotValidException.cs | 1 + crypto/src/cms/PKCS5Scheme2PBEKey.cs | 8 ++++--- crypto/src/cms/PKCS5Scheme2UTF8PBEKey.cs | 8 ++++--- 9 files changed, 37 insertions(+), 6 deletions(-) diff --git a/crypto/src/cms/CMSAttributeTableGenerationException.cs b/crypto/src/cms/CMSAttributeTableGenerationException.cs index 414d96c6fb..6a8136467d 100644 --- a/crypto/src/cms/CMSAttributeTableGenerationException.cs +++ b/crypto/src/cms/CMSAttributeTableGenerationException.cs @@ -3,6 +3,7 @@ namespace Org.BouncyCastle.Cms { + /// Exception thrown when a CMS signed or authenticated attribute table cannot be generated. [Serializable] public class CmsAttributeTableGenerationException : CmsException diff --git a/crypto/src/cms/CMSException.cs b/crypto/src/cms/CMSException.cs index 09850e7220..c78e7706a8 100644 --- a/crypto/src/cms/CMSException.cs +++ b/crypto/src/cms/CMSException.cs @@ -3,6 +3,7 @@ namespace Org.BouncyCastle.Cms { + /// General exception thrown when CMS processing fails. [Serializable] public class CmsException : Exception diff --git a/crypto/src/cms/CMSPBEKey.cs b/crypto/src/cms/CMSPBEKey.cs index 61825c233e..ef298785fc 100644 --- a/crypto/src/cms/CMSPBEKey.cs +++ b/crypto/src/cms/CMSPBEKey.cs @@ -11,6 +11,10 @@ namespace Org.BouncyCastle.Cms { + /// + /// Base class for password-based keys used with CMS enveloped-data recipients. Passed to + /// . + /// 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; + /// Creates a PBE key from explicit password, salt, and iteration count. + /// The password characters. + /// The PBKDF2 salt. + /// The PBKDF2 iteration count. public CmsPbeKey( char[] password, byte[] salt, @@ -30,6 +38,10 @@ public CmsPbeKey( this.iterationCount = iterationCount; } + /// Creates a PBE key from a password and PBKDF2 AlgorithmIdentifier. + /// The password characters. + /// The PBKDF2 algorithm identifier. + /// The key derivation algorithm is not PBKDF2. public CmsPbeKey( char[] password, AlgorithmIdentifier keyDerivationAlgorithm) @@ -49,6 +61,7 @@ public CmsPbeKey( } #if NETCOREAPP2_1_OR_GREATER || NETSTANDARD2_1_OR_GREATER + /// Creates a PBE key from explicit password, salt, and iteration count. public CmsPbeKey(ReadOnlySpan password, ReadOnlySpan salt, int iterationCount) { this.password = password.ToArray(); @@ -56,6 +69,8 @@ public CmsPbeKey(ReadOnlySpan password, ReadOnlySpan salt, int itera this.iterationCount = iterationCount; } + /// Creates a PBE key from a password and PBKDF2 AlgorithmIdentifier. + /// The key derivation algorithm is not PBKDF2. public CmsPbeKey(ReadOnlySpan password, AlgorithmIdentifier keyDerivationAlgorithm) { if (!keyDerivationAlgorithm.Algorithm.Equals(PkcsObjectIdentifiers.IdPbkdf2)) @@ -79,26 +94,32 @@ public CmsPbeKey(ReadOnlySpan password, AlgorithmIdentifier keyDerivationA Arrays.ZeroMemory(this.password); } + /// Gets a copy of the PBKDF2 salt. public byte[] Salt { get { return Arrays.Clone(salt); } } + /// Gets the PBKDF2 iteration count. public int IterationCount { get { return iterationCount; } } + /// Gets the key algorithm name (PKCS5S2). public string Algorithm { get { return "PKCS5S2"; } } + /// Gets the encoding format name (RAW). public string Format { get { return "RAW"; } } + /// Returns null; raw encoding is not supported. + /// Always null. public byte[] GetEncoded() { return null; diff --git a/crypto/src/cms/CMSStreamException.cs b/crypto/src/cms/CMSStreamException.cs index 1667a0c4f4..fa8a02bb2e 100644 --- a/crypto/src/cms/CMSStreamException.cs +++ b/crypto/src/cms/CMSStreamException.cs @@ -4,6 +4,7 @@ namespace Org.BouncyCastle.Cms { + /// Exception thrown when CMS streaming operations fail. [Serializable] public class CmsStreamException : IOException diff --git a/crypto/src/cms/CmsAlgorithmNotAllowedException.cs b/crypto/src/cms/CmsAlgorithmNotAllowedException.cs index a23b9cd343..80e22a9421 100644 --- a/crypto/src/cms/CmsAlgorithmNotAllowedException.cs +++ b/crypto/src/cms/CmsAlgorithmNotAllowedException.cs @@ -3,6 +3,7 @@ namespace Org.BouncyCastle.Cms { + /// Exception thrown when a CMS operation does not permit the requested algorithm. [Serializable] public class CmsAlgorithmNotAllowedException : CmsException diff --git a/crypto/src/cms/CmsTagLengthException.cs b/crypto/src/cms/CmsTagLengthException.cs index ca28b56f41..cc9a3f6ee9 100644 --- a/crypto/src/cms/CmsTagLengthException.cs +++ b/crypto/src/cms/CmsTagLengthException.cs @@ -3,6 +3,7 @@ namespace Org.BouncyCastle.Cms { + /// Exception thrown when an authenticated CMS content tag length is invalid. [Serializable] public class CmsTagLengthException : CmsException diff --git a/crypto/src/cms/CmsVerifierCertificateNotValidException.cs b/crypto/src/cms/CmsVerifierCertificateNotValidException.cs index 2ba6cec202..37905a1d0b 100644 --- a/crypto/src/cms/CmsVerifierCertificateNotValidException.cs +++ b/crypto/src/cms/CmsVerifierCertificateNotValidException.cs @@ -3,6 +3,7 @@ namespace Org.BouncyCastle.Cms { + /// Exception thrown when a signer certificate is not valid at the signing time. [Serializable] public class CmsVerifierCertificateNotValidException : CmsException diff --git a/crypto/src/cms/PKCS5Scheme2PBEKey.cs b/crypto/src/cms/PKCS5Scheme2PBEKey.cs index df6323d840..ab04b9bd43 100644 --- a/crypto/src/cms/PKCS5Scheme2PBEKey.cs +++ b/crypto/src/cms/PKCS5Scheme2PBEKey.cs @@ -8,12 +8,11 @@ namespace Org.BouncyCastle.Cms { - /// - /// PKCS5 scheme-2 - password converted to bytes assuming ASCII. - /// + /// PKCS#5 scheme 2 PBE key with the password encoded as ASCII bytes. public class Pkcs5Scheme2PbeKey : CmsPbeKey { + /// public Pkcs5Scheme2PbeKey( char[] password, byte[] salt, @@ -22,6 +21,7 @@ public Pkcs5Scheme2PbeKey( { } + /// public Pkcs5Scheme2PbeKey( char[] password, AlgorithmIdentifier keyDerivationAlgorithm) @@ -30,11 +30,13 @@ public Pkcs5Scheme2PbeKey( } #if NETCOREAPP2_1_OR_GREATER || NETSTANDARD2_1_OR_GREATER + /// public Pkcs5Scheme2PbeKey(ReadOnlySpan password, ReadOnlySpan salt, int iterationCount) : base(password, salt, iterationCount) { } + /// public Pkcs5Scheme2PbeKey(ReadOnlySpan password, AlgorithmIdentifier keyDerivationAlgorithm) : base(password, keyDerivationAlgorithm) { diff --git a/crypto/src/cms/PKCS5Scheme2UTF8PBEKey.cs b/crypto/src/cms/PKCS5Scheme2UTF8PBEKey.cs index bde3e5a730..6ce06425b2 100644 --- a/crypto/src/cms/PKCS5Scheme2UTF8PBEKey.cs +++ b/crypto/src/cms/PKCS5Scheme2UTF8PBEKey.cs @@ -8,12 +8,11 @@ namespace Org.BouncyCastle.Cms { - /** - * PKCS5 scheme-2 - password converted to bytes using UTF-8. - */ + /// PKCS#5 scheme 2 PBE key with the password encoded as UTF-8 bytes. public class Pkcs5Scheme2Utf8PbeKey : CmsPbeKey { + /// public Pkcs5Scheme2Utf8PbeKey( char[] password, byte[] salt, @@ -22,6 +21,7 @@ public Pkcs5Scheme2Utf8PbeKey( { } + /// public Pkcs5Scheme2Utf8PbeKey( char[] password, AlgorithmIdentifier keyDerivationAlgorithm) @@ -30,11 +30,13 @@ public Pkcs5Scheme2Utf8PbeKey( } #if NETCOREAPP2_1_OR_GREATER || NETSTANDARD2_1_OR_GREATER + /// public Pkcs5Scheme2Utf8PbeKey(ReadOnlySpan password, ReadOnlySpan salt, int iterationCount) : base(password, salt, iterationCount) { } + /// public Pkcs5Scheme2Utf8PbeKey(ReadOnlySpan password, AlgorithmIdentifier keyDerivationAlgorithm) : base(password, keyDerivationAlgorithm) {