Added missing XML documentation and resolved some discrepancies in existing comments

WE2-1008

Signed-off-by: Mihkel Kivisild [email protected]

Author: Mihkel Kivisild

src/WebEid.Security.Tests/Certificate/CertificateDataTest.cs

@@ -2,7 +2,6 @@ namespace WebEid.Security.Tests.Certificate
 {
     using System.Security.Cryptography.X509Certificates;
     using NUnit.Framework;
-    using WebEid.Security.Exceptions;
     using WebEid.Security.Tests.TestUtils;
     using WebEid.Security.Util;
 

src/WebEid.Security.Tests/TestUtils/OcspServiceMaker.cs

@@ -1,4 +1,4 @@
-/*
+/*
  * Copyright © 2020-2024 Estonian Information System Authority
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -37,8 +37,8 @@ public class OcspServiceMaker
 
         static OcspServiceMaker() => TrustedCaCertificates = new List<X509Certificate2>
             {
-                new X509Certificate2(Certificates.GetTestEsteid2015Ca()),
-                new X509Certificate2(Certificates.GetTestEsteid2018Ca())
+                new(Certificates.GetTestEsteid2015Ca()),
+                new(Certificates.GetTestEsteid2018Ca())
             };
 
         public static OcspServiceProvider GetAiaOcspServiceProvider() => new(null, GetAiaOcspServiceConfiguration());

src/WebEid.Security.Tests/Validator/Ocsp/OcspResponseValidatorTests.cs

@@ -26,13 +26,11 @@ namespace WebEid.Security.Tests.Validator.Ocsp
     using Org.BouncyCastle.Ocsp;
     using Security.Validator.Ocsp;
     using WebEid.Security.Validator;
-    using Org.BouncyCastle.Asn1;
     using Org.BouncyCastle.Asn1.Ocsp;
     using System.Globalization;
     using WebEid.Security.Exceptions;
     using WebEid.Security.Tests.TestUtils;
     using WebEid.Security.Util;
-    using System.Runtime.CompilerServices;
 
     [TestFixture]
     public class OcspResponseValidatorTests

src/WebEid.Security.Tests/WebEid.Security.Tests.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFramework>net6.0</TargetFramework>
+    <TargetFramework>net8.0</TargetFramework>
 
     <IsPackable>false</IsPackable>
 

src/WebEid.Security/Challenge/ChallengeNonce.cs

@@ -1,4 +1,4 @@
-/*
+/*
  * Copyright © 2020-2024 Estonian Information System Authority
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -23,11 +23,27 @@ namespace WebEid.Security.Challenge
 {
     using System;
 
+    /// <summary>
+    /// Represents a challenge nonce used in the Web eID system.
+    /// </summary>
     public class ChallengeNonce
     {
+        /// <summary>
+        /// The base64-encoded value of the nonce.
+        /// </summary>
         public string Base64EncodedNonce { get; private set; }
+
+        /// <summary>
+        /// The expiration time for the nonce.
+        /// </summary>
         public DateTime ExpirationTime { get; private set; }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ChallengeNonce"/> class.
+        /// </summary>
+        /// <param name="base64EncodedNonce">The base64-encoded value of the nonce.</param>
+        /// <param name="expirationTime">The expiration time for the nonce.</param>
+        /// <exception cref="ArgumentNullException">Thrown when the provided base64EncodedNonce is null.</exception>
         public ChallengeNonce(string base64EncodedNonce, DateTime expirationTime)
         {
             this.Base64EncodedNonce = base64EncodedNonce ?? throw new ArgumentNullException(nameof(base64EncodedNonce));

src/WebEid.Security/Challenge/ChallengeNonceGenerator.cs

@@ -1,4 +1,4 @@
-/*
+/*
  * Copyright © 2020-2024 Estonian Information System Authority
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -25,16 +25,20 @@ namespace WebEid.Security.Challenge
     using System.Security.Cryptography;
     using Util;
 
+    /// <summary>
+    /// Generates and stores cryptographic nonces for the Web eID system.
+    /// </summary>
     public sealed class ChallengeNonceGenerator : IChallengeNonceGenerator
     {
         private readonly IChallengeNonceStore store;
         private readonly RandomNumberGenerator randomNumberGenerator;
 
         /// <summary>
-        /// Initializes a new instance of NonceGenerator
+        /// Initializes a new instance of the <see cref="ChallengeNonceGenerator"/> class.
         /// </summary>
+        /// <param name="randomNumberGenerator">The source of random bytes for generating nonces.</param>
         /// <param name="store">The store where generated nonce values will be stored.</param>
-        /// <param name="randomNumberGenerator">The source of random bytes for the nonce.</param>
+        /// <exception cref="ArgumentNullException">Thrown when either randomNumberGenerator or store is null.</exception>
         public ChallengeNonceGenerator(RandomNumberGenerator randomNumberGenerator, IChallengeNonceStore store)
         {
             this.randomNumberGenerator = randomNumberGenerator ?? throw new ArgumentNullException(nameof(randomNumberGenerator), "Secure random generator must not be null");
@@ -43,16 +47,18 @@ public ChallengeNonceGenerator(RandomNumberGenerator randomNumberGenerator, ICha
 
         /// <summary>
         /// Generates a cryptographic nonce, a large random number that can be used only once,
-        /// and stores it in a ChallengeNonceStore.
+        /// and stores it in the specified ChallengeNonceStore.
         /// </summary>
-        /// <param name="ttl">Challenge nonce time-to-live duration. When the time-to-live passes, the nonce is considered to be expired.</param>
-        /// <returns>a ChallengeNonce that contains the Base64-encoded nonce and its expiry time</returns>
+        /// <param name="ttl">The time-to-live duration for the nonce. When the time-to-live passes, the nonce is considered expired.</param>
+        /// <returns>A ChallengeNonce that contains the Base64-encoded nonce and its expiry time.</returns>
+        /// <exception cref="ArgumentOutOfRangeException">Thrown when the provided ttl is negative or zero.</exception>
         public ChallengeNonce GenerateAndStoreNonce(TimeSpan ttl)
         {
             if (ttl.IsNegativeOrZero())
             {
                 throw new ArgumentOutOfRangeException(nameof(ttl), "Nonce time-to-live duration must be greater than zero");
             }
+
             var nonceBytes = new byte[IChallengeNonceGenerator.NonceLength];
             this.randomNumberGenerator.GetBytes(nonceBytes);
             var base64StringNonce = Convert.ToBase64String(nonceBytes);

src/WebEid.Security/Challenge/IChallengeNonceStore.cs

@@ -55,11 +55,8 @@ public interface IChallengeNonceStore
         /// </remarks>
         ChallengeNonce GetAndRemove()
         {
-            var challengeNonce = GetAndRemoveImpl();
-            if (challengeNonce == null)
-            {
-                throw new ChallengeNonceNotFoundException();
-            }
+            var challengeNonce = GetAndRemoveImpl() ?? throw new ChallengeNonceNotFoundException();
+
             if (DateTimeProvider.UtcNow >= challengeNonce.ExpirationTime)
             {
                 throw new ChallengeNonceExpiredException();

src/WebEid.Security/Exceptions/AuthTokenException.cs

@@ -1,4 +1,4 @@
-/*
+/*
  * Copyright © 2020-2024 Estonian Information System Authority
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -26,19 +26,33 @@ namespace WebEid.Security.Exceptions
     using System.Runtime.Serialization;
 
     /// <summary>
-    /// Base class for all authentication token validation exceptions.
+    /// Base class for all authentication token validation exceptions in the Web eID system.
     /// </summary>
     [Serializable]
     public abstract class AuthTokenException : Exception
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AuthTokenException"/> class with the specified error message.
+        /// </summary>
+        /// <param name="msg">The error message.</param>
         protected AuthTokenException(string msg) : base(msg)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AuthTokenException"/> class with the specified error message and inner exception.
+        /// </summary>
+        /// <param name="msg">The error message.</param>
+        /// <param name="innerException">The inner exception.</param>
         protected AuthTokenException(string msg, Exception innerException) : base(msg, innerException)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AuthTokenException"/> class from serialized data.
+        /// </summary>
+        /// <param name="info">The <see cref="SerializationInfo"/> that holds the serialized object data.</param>
+        /// <param name="context">The <see cref="StreamingContext"/> that contains contextual information about the source or destination.</param>
         [ExcludeFromCodeCoverage]
         protected AuthTokenException(SerializationInfo info, StreamingContext context) : base(info, context) { }
     }

src/WebEid.Security/Exceptions/AuthTokenParseException.cs

@@ -1,4 +1,4 @@
-/*
+/*
  * Copyright © 2020-2024 Estonian Information System Authority
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -26,23 +26,41 @@ namespace WebEid.Security.Exceptions
     using System.Runtime.Serialization;
 
     /// <summary>
-    /// Thrown when authentication token parsing fails.
+    /// Represents an exception thrown when authentication token parsing fails in the Web eID system.
     /// </summary>
     [Serializable]
     public class AuthTokenParseException : AuthTokenException
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AuthTokenParseException"/> class with the specified error message.
+        /// </summary>
+        /// <param name="message">The error message.</param>
         public AuthTokenParseException(string message) : base(message)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AuthTokenParseException"/> class with the specified inner exception.
+        /// </summary>
+        /// <param name="innerException">The inner exception.</param>
         public AuthTokenParseException(Exception innerException) : this("Error parsing token", innerException)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AuthTokenParseException"/> class with the specified error message and inner exception.
+        /// </summary>
+        /// <param name="message">The error message.</param>
+        /// <param name="innerException">The inner exception.</param>
         public AuthTokenParseException(string message, Exception innerException) : base(message, innerException)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AuthTokenParseException"/> class from serialized data.
+        /// </summary>
+        /// <param name="info">The <see cref="SerializationInfo"/> that holds the serialized object data.</param>
+        /// <param name="context">The <see cref="StreamingContext"/> that contains contextual information about the source or destination.</param>
         [ExcludeFromCodeCoverage]
         protected AuthTokenParseException(SerializationInfo info, StreamingContext context) : base(info, context) { }
     }

src/WebEid.Security/Exceptions/AuthTokenSignatureValidationException.cs

@@ -1,4 +1,4 @@
-/*
+/*
  * Copyright © 2020-2024 Estonian Information System Authority
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -26,22 +26,37 @@ namespace WebEid.Security.Exceptions
     using System.Runtime.Serialization;
 
     /// <summary>
-    /// Thrown when authentication token signature validation fails.
+    /// Represents an exception thrown when authentication token signature validation fails in the Web eID system.
     /// </summary>
     [Serializable]
     public class AuthTokenSignatureValidationException : AuthTokenException
     {
-        public const string ErrorMessage = "Token signature validation has failed";
-
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AuthTokenSignatureValidationException"/> class.
+        /// </summary>
         public AuthTokenSignatureValidationException() : base(ErrorMessage)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AuthTokenSignatureValidationException"/> class with the specified inner exception.
+        /// </summary>
+        /// <param name="innerException">The inner exception.</param>
         public AuthTokenSignatureValidationException(Exception innerException) : base(ErrorMessage, innerException)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AuthTokenSignatureValidationException"/> class from serialized data.
+        /// </summary>
+        /// <param name="info">The <see cref="SerializationInfo"/> that holds the serialized object data.</param>
+        /// <param name="context">The <see cref="StreamingContext"/> that contains contextual information about the source or destination.</param>
         [ExcludeFromCodeCoverage]
         protected AuthTokenSignatureValidationException(SerializationInfo info, StreamingContext context) : base(info, context) { }
+
+        /// <summary>
+        /// The error message indicating that token signature validation has failed.
+        /// </summary>
+        public const string ErrorMessage = "Token signature validation has failed";
     }
 }