From 4c1778b60582d8c5af6138e75ec8cd9ab4170d8b Mon Sep 17 00:00:00 2001
From: Joe Shook <joeshook@gmail.com>
Date: Thu, 5 Dec 2024 08:55:46 -0800
Subject: [PATCH] Allow easier implementation of IX509CertificateDatabase and
 BouncyCastleSecureMimeContext (#1111)

While implementing IX509CertificateDatabase and extending BouncyCastleSecureMimeContext I ran into a few internal methods I would like to reuse for consistency.

Co-authored-by: Joseph Shook <Joseph.Shook@Surescripts.com>
---
 .../BouncyCastleCertificateExtensions.cs      | 37 ++++++++++++--
 MimeKit/Cryptography/X509KeyUsageFlags.cs     | 48 ++++++++++++++++++-
 2 files changed, 81 insertions(+), 4 deletions(-)

diff --git a/MimeKit/Cryptography/BouncyCastleCertificateExtensions.cs b/MimeKit/Cryptography/BouncyCastleCertificateExtensions.cs
index f98b3b6da8..7d8e61740e 100644
--- a/MimeKit/Cryptography/BouncyCastleCertificateExtensions.cs
+++ b/MimeKit/Cryptography/BouncyCastleCertificateExtensions.cs
@@ -67,7 +67,15 @@ public static X509Certificate2 AsX509Certificate2 (this X509Certificate certific
 			return new X509Certificate2 (certificate.GetEncoded ());
 		}
 
-		internal static bool IsSelfSigned (this X509Certificate certificate)
+		/// <summary>
+		/// Determines whether the specified certificate is self-signed.
+		/// </summary>
+		/// <remarks>
+		/// A certificate is considered self-signed if the subject and issuer names are the same.
+		/// </remarks>
+		/// <param name="certificate">The certificate to check.</param>
+		/// <returns><c>true</c> if the certificate is self-signed; otherwise, <c>false</c>.</returns>
+		public static bool IsSelfSigned (this X509Certificate certificate)
 		{
 			return certificate.SubjectDN.Equivalent (certificate.IssuerDN);
 		}
@@ -259,7 +267,20 @@ public static PublicKeyAlgorithm GetPublicKeyAlgorithm (this X509Certificate cer
 			return PublicKeyAlgorithm.None;
 		}
 
-		internal static X509KeyUsageFlags GetKeyUsageFlags (bool[] usage)
+		/// <summary>
+		/// Generates an X509KeyUsageFlags value based on the provided usage bit array.
+		/// </summary>
+		/// <param name="usage">A boolean array representing the key usage bits.
+		/// Each index corresponds to a specific value defined  by <see cref="X509KeyUsageBits"/>
+		/// </param>
+		/// <returns>
+		/// An X509KeyUsageFlags value that represents the combined key usage flags.
+		/// </returns>
+		/// <remarks>
+		/// If the usage array is null, all key usage flags are considered enabled by
+		/// returning a <see cref="X509KeyUsageFlags.None"/>
+		/// </remarks>
+		public static X509KeyUsageFlags GetKeyUsageFlags (bool[] usage)
 		{
 			var flags = X509KeyUsageFlags.None;
 
@@ -353,7 +374,17 @@ public static EncryptionAlgorithm[] GetEncryptionAlgorithms (this X509Certificat
 			return new EncryptionAlgorithm[] { EncryptionAlgorithm.TripleDes };
 		}
 
-		internal static bool IsDelta (this X509Crl crl)
+		/// <summary>
+		/// Determines whether the specified X.509 CRL is a delta CRL.
+		/// </summary>
+		/// <remarks>
+		/// A delta CRL contains updates to a previously issued CRL. This method checks
+		/// if the CRL contains the Delta CRL Indicator extension.
+		/// <note>The X.509 delta CRL indicator extension must be marked critical to be found.</note>
+		/// </remarks>
+		/// <param name="crl">The X.509 CRL to check.</param>
+		/// <returns><c>true</c> if the specified CRL is a delta CRL; otherwise, <c>false</c>.</returns>
+		public static bool IsDelta (this X509Crl crl)
 		{
 			var critical = crl.GetCriticalExtensionOids ();
 
diff --git a/MimeKit/Cryptography/X509KeyUsageFlags.cs b/MimeKit/Cryptography/X509KeyUsageFlags.cs
index 9febdf1e1d..0411c3eaa9 100644
--- a/MimeKit/Cryptography/X509KeyUsageFlags.cs
+++ b/MimeKit/Cryptography/X509KeyUsageFlags.cs
@@ -107,15 +107,61 @@ public enum X509KeyUsageFlags {
 		DecipherOnly     = 1 << 15
 	}
 
-	enum X509KeyUsageBits {
+	/// <summary>
+	/// X.509 key usage bits.
+	/// </summary>
+	/// <remarks>
+	/// <para>The X.509 Key Usage Bits can be used to determine what operations
+	/// a certificate can be used for which is similar to <see cref="X509KeyUsageFlags"/> but
+	/// the usage of this is enum represents a position in a bit array.</para> 
+	/// </remarks>
+	public enum X509KeyUsageBits
+	{
+		/// <summary>
+		/// The key may be used for digitally signing data.
+		/// </summary>
 		DigitalSignature,
+
+		/// <summary>
+		/// The key may be used to verify digital signatures used to
+		/// provide a non-repudiation service.
+		/// </summary>
 		NonRepudiation,
+
+		/// <summary>
+		/// The key is meant to be used for key encipherment.
+		/// </summary>
 		KeyEncipherment,
+
+		/// <summary>
+		/// The key may be used for data encipherment.
+		/// </summary>
 		DataEncipherment,
+
+		/// <summary>
+		/// The key is meant to be used for key agreement.
+		/// </summary>
 		KeyAgreement,
+
+		/// <summary>
+		/// The key may be used for verifying signatures on certificates.
+		/// </summary>
 		KeyCertSign,
+
+		/// <summary>
+		/// The key may be used for verifying signatures on
+		/// certificate revocation lists (CRLs).
+		/// </summary>
 		CrlSign,
+
+		/// <summary>
+		/// The key may only be used for enciphering data during key agreement.
+		/// </summary>
 		EncipherOnly,
+
+		/// <summary>
+		/// The key may only be used for deciphering data during key agreement.
+		/// </summary>
 		DecipherOnly,
 	}
 }