Generate XML documentation file (#502)

Directory.Build.props

@@ -18,6 +18,12 @@
     <SupportedTargetFrameworks>net6.0</SupportedTargetFrameworks>
     <ImplicitUsings>enable</ImplicitUsings>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <!-- 
+      Temporary disabling of CS1591 (Missing XML comment for publicly visible type or member) warning
+      Make sure to re-enable it when https://github.com/passwordless-lib/fido2-net-lib/issues/501 is resolved.
+    -->
+    <NoWarn>$(NoWarn);CS1591</NoWarn>
   </PropertyGroup>
 
   <!-- Language + Compiler Settings-->

Src/Fido2.AspNet/Fido2NetLibBuilderExtensions.cs

@@ -99,7 +99,7 @@ public interface IFido2MetadataServiceBuilder
 public class Fido2NetLibBuilder : IFido2NetLibBuilder, IFido2MetadataServiceBuilder
 {
     /// <summary>
-    /// Initializes a new instance of the <see cref="IdentityServerBuilder"/> class.
+    /// Initializes a new instance of the <see cref="Fido2NetLibBuilder"/> class.
     /// </summary>
     /// <param name="services">The services.</param>
     /// <exception cref="System.ArgumentNullException">services</exception>

Src/Fido2/AuthenticatorAssertionResponse.cs

@@ -46,9 +46,12 @@ public static AuthenticatorAssertionResponse Parse(AuthenticatorAssertionRawResp
     /// Implements algorithm from https://www.w3.org/TR/webauthn/#verifying-assertion.
     /// </summary>
     /// <param name="options">The original assertion options that was sent to the client.</param>
+    /// <param name="config"></param>
     /// <param name="storedPublicKey">The stored public key for this CredentialId.</param>
+    /// <param name="storedDevicePublicKeys">The stored device public key for this CredentialId.</param>
     /// <param name="storedSignatureCounter">The stored counter value for this CredentialId</param>
     /// <param name="isUserHandleOwnerOfCredId">A function that returns <see langword="true"/> if user handle is owned by the credential ID.</param>
+    /// <param name="metadataService"></param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> used to propagate notifications that the operation should be canceled.</param>
     public async Task<VerifyAssertionResult> VerifyAsync(
         AssertionOptions options,
@@ -186,7 +189,8 @@ public async Task<VerifyAssertionResult> VerifyAsync(
     /// verification steps are performed in the context of this step of § 7.2 Verifying an Authentication Assertion using 
     /// these variables established therein: credential, clientExtensionResults, authData, and hash. Relying Party policy 
     /// may specify whether a response without a devicePubKey is acceptable.
-    /// <see cref="https://w3c.github.io/webauthn/#sctn-device-publickey-extension-verification-get"/>
+    /// <see href="https://w3c.github.io/webauthn/#sctn-device-publickey-extension-verification-get"/>
+    /// <param name="storedDevicePublicKeys"></param>
     /// <param name="clientExtensionResults"></param>
     /// <param name="authData"></param>
     /// <param name="hash"></param>

Src/Fido2/AuthenticatorAttestationResponse.cs

@@ -209,10 +209,13 @@ public async Task<RegisteredPublicKeyCredential> VerifyAsync(
     /// credential, clientExtensionResults, authData, and hash. 
     /// Relying Party policy may specify whether a response without a devicePubKey is acceptable.
     /// </summary>
+    /// <param name="config"></param>
+    /// <param name="metadataService"></param>
     /// <param name="clientExtensionResults"></param>
     /// <param name="authData"></param>
     /// <param name="hash"></param>
-    /// <see cref="https://w3c.github.io/webauthn/#sctn-device-publickey-extension-verification-create"/> 
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> used to propagate notifications that the operation should be canceled.</param>
+    /// <see href="https://w3c.github.io/webauthn/#sctn-device-publickey-extension-verification-create"/> 
     private async Task<byte[]> DevicePublicKeyRegistrationAsync(
         Fido2Configuration config,
         IMetadataService? metadataService,

Src/Fido2/Fido2.cs

@@ -8,7 +8,7 @@
 namespace Fido2NetLib;
 
 /// <summary>
-/// Public API for parsing and verifying FIDO2 attestation & assertion responses.
+/// Public API for parsing and verifying FIDO2 attestation and assertion responses.
 /// </summary>
 public class Fido2 : IFido2
 {
@@ -26,8 +26,10 @@ public Fido2(
     /// <summary>
     /// Returns CredentialCreateOptions including a challenge to be sent to the browser/authenticator to create new credentials.
     /// </summary>
-    /// <returns></returns>
+    /// <param name="user"></param>
     /// <param name="excludeCredentials">Recommended. This member is intended for use by Relying Parties that wish to limit the creation of multiple credentials for the same account on a single authenticator. The client is requested to return an error if the new credential would be created on an authenticator that also contains one of the credentials enumerated in this parameter.</param>
+    /// <param name="extensions"></param>
+    /// <returns></returns>
     public CredentialCreateOptions RequestNewCredential(
         Fido2User user,
         IReadOnlyList<PublicKeyCredentialDescriptor> excludeCredentials,
@@ -39,9 +41,12 @@ public CredentialCreateOptions RequestNewCredential(
     /// <summary>
     /// Returns CredentialCreateOptions including a challenge to be sent to the browser/authenticator to create new credentials.
     /// </summary>
-    /// <returns></returns>
-    /// <param name="attestationPreference">This member is intended for use by Relying Parties that wish to express their preference for attestation conveyance. The default is none.</param>
+    /// <param name="user"></param>
     /// <param name="excludeCredentials">Recommended. This member is intended for use by Relying Parties that wish to limit the creation of multiple credentials for the same account on a single authenticator. The client is requested to return an error if the new credential would be created on an authenticator that also contains one of the credentials enumerated in this parameter.</param>
+    /// <param name="authenticatorSelection"></param>
+    /// <param name="attestationPreference">This member is intended for use by Relying Parties that wish to express their preference for attestation conveyance. The default is none.</param>
+    /// <param name="extensions"></param>
+    /// <returns></returns>
     public CredentialCreateOptions RequestNewCredential(
         Fido2User user,
         IReadOnlyList<PublicKeyCredentialDescriptor> excludeCredentials,
@@ -82,6 +87,9 @@ public async Task<MakeNewCredentialResult> MakeNewCredentialAsync(
     /// <summary>
     /// Returns AssertionOptions including a challenge to the browser/authenticator to assert existing credentials and authenticate a user.
     /// </summary>
+    /// <param name="allowedCredentials"></param>
+    /// <param name="userVerification"></param>
+    /// <param name="extensions"></param>
     /// <returns></returns>
     public AssertionOptions GetAssertionOptions(
         IReadOnlyList<PublicKeyCredentialDescriptor> allowedCredentials,

Src/Fido2/IMetadataService.cs

@@ -10,6 +10,7 @@ public interface IMetadataService
     /// Gets the metadata payload entry by a guid asynchronously.
     /// </summary>
     /// <param name="aaguid">The Authenticator Attestation GUID.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> used to propagate notifications that the operation should be canceled.</param>
     /// <returns>Returns the entry; Otherwise <c>null</c>.</returns>
     Task<MetadataBLOBPayloadEntry?> GetEntryAsync(Guid aaguid, CancellationToken cancellationToken = default);
 

Src/Fido2/Objects/AttestedCredentialData.cs

@@ -10,7 +10,7 @@ public sealed class AttestedCredentialData
 {
     /// <summary>
     /// Minimum length of the attested credential data structure. AAGUID + credentialID length + credential ID + credential public key.
-    /// <see cref="https://www.w3.org/TR/webauthn/#attested-credential-data"/>
+    /// <see href="https://www.w3.org/TR/webauthn/#attested-credential-data"/>
     /// </summary>
     private const int _minLength = 20; // Marshal.SizeOf(typeof(Guid)) + sizeof(ushort) + sizeof(byte) + sizeof(byte)
 
@@ -34,20 +34,20 @@ public AttestedCredentialData(Guid aaGuid, byte[] credentialId, CredentialPublic
 
     /// <summary>
     /// The AAGUID of the authenticator. Can be used to identify the make and model of the authenticator.
-    /// <see cref="https://www.w3.org/TR/webauthn/#aaguid"/>
+    /// <see href="https://www.w3.org/TR/webauthn/#aaguid"/>
     /// </summary>
     public Guid AaGuid { get; }
 
     /// <summary>
     /// A probabilistically-unique byte sequence identifying a public key credential source and its authentication assertions.
-    /// <see cref="https://www.w3.org/TR/webauthn/#credential-id"/>
+    /// <see href="https://www.w3.org/TR/webauthn/#credential-id"/>
     /// </summary>
     public byte[] CredentialId { get; }
 
     /// <summary>
     /// The credential public key encoded in COSE_Key format, as defined in 
     /// Section 7 of RFC8152, using the CTAP2 canonical CBOR encoding form.
-    /// <see cref="https://www.w3.org/TR/webauthn/#credential-public-key"/>
+    /// <see href="https://www.w3.org/TR/webauthn/#credential-public-key"/>
     /// </summary>
     public CredentialPublicKey CredentialPublicKey { get; }
 

Src/Fido2/Objects/AuthenticatorData.cs

@@ -11,7 +11,7 @@ public sealed class AuthenticatorData
 {
     /// <summary>
     /// Minimum length of the authenticator data structure.
-    /// <see cref="https://www.w3.org/TR/webauthn/#sec-authenticator-data"/>
+    /// <see href="https://www.w3.org/TR/webauthn/#sec-authenticator-data"/>
     /// </summary>
     internal const int MinLength = SHA256HashLenBytes + sizeof(AuthenticatorFlags) + sizeof(uint);
 
@@ -55,13 +55,13 @@ public AuthenticatorData(byte[] rpIdHash, AuthenticatorFlags flags, uint signCou
 
     /// <summary>
     /// UserPresent indicates that the user presence test has completed successfully.
-    /// <see cref="https://www.w3.org/TR/webauthn/#up"/>
+    /// <see href="https://www.w3.org/TR/webauthn/#up"/>
     /// </summary>
     public bool UserPresent => _flags.HasFlag(AuthenticatorFlags.UP);
 
     /// <summary>
     /// UserVerified indicates that the user verification process has completed successfully.
-    /// <see cref="https://www.w3.org/TR/webauthn/#uv"/>
+    /// <see href="https://www.w3.org/TR/webauthn/#uv"/>
     /// </summary>
     public bool UserVerified => _flags.HasFlag(AuthenticatorFlags.UV);
 
@@ -70,27 +70,27 @@ public AuthenticatorData(byte[] rpIdHash, AuthenticatorFlags flags, uint signCou
     /// Backup eligibility is signaled in authenticator data's flags along with the current backup state. 
     /// Backup eligibility is a credential property and is permanent for a given public key credential source. 
     /// A backup eligible public key credential source is referred to as a multi-device credential whereas one that is not backup eligible is referred to as a single-device credential.
-    /// <see cref="https://w3c.github.io/webauthn/#backup-eligibility"/>
+    /// <see href="https://w3c.github.io/webauthn/#backup-eligibility"/>
     /// </summary>
     public bool IsBackupEligible => _flags.HasFlag(AuthenticatorFlags.BE);
 
     /// <summary>
     /// The current backup state of a multi-device credential as determined by the current managing authenticator. 
     /// Backup state is signaled in authenticator data's flags and can change over time.
-    /// <see cref="https://w3c.github.io/webauthn/#backup-state"/>
+    /// <see href="https://w3c.github.io/webauthn/#backup-state"/>
     /// </summary>
     public bool IsBackedUp => _flags.HasFlag(AuthenticatorFlags.BS);
 
     /// <summary>
     /// HasAttestedCredentialData indicates that the authenticator added attested credential data to the authenticator data.
-    /// <see cref="https://www.w3.org/TR/webauthn/#attested-credential-data"/>
+    /// <see href="https://www.w3.org/TR/webauthn/#attested-credential-data"/>
     /// </summary>
     [MemberNotNullWhen(true, nameof(AttestedCredentialData))]
     public bool HasAttestedCredentialData => _flags.HasFlag(AuthenticatorFlags.AT);
 
     /// <summary>
     /// HasExtensionsData indicates that the authenticator added extension data to the authenticator data.
-    /// <see cref="https://www.w3.org/TR/webauthn/#authdataextensions"/>
+    /// <see href="https://www.w3.org/TR/webauthn/#authdataextensions"/>
     /// </summary>
     [MemberNotNullWhen(true, nameof(Extensions))]
     public bool HasExtensionsData => _flags.HasFlag(AuthenticatorFlags.ED);

Src/Fido2/Objects/AuthenticatorFlags.cs

@@ -4,14 +4,14 @@ namespace Fido2NetLib.Objects;
 
 /// <summary>
 /// Authenticator data flags 
-/// <see cref="https://www.w3.org/TR/webauthn/#flags"/>
+/// <see href="https://www.w3.org/TR/webauthn/#flags"/>
 /// </summary>
 [Flags]
 public enum AuthenticatorFlags : byte
 {
     /// <summary>
     /// User Present indicates that the user presence test has completed successfully.
-    /// <see cref="https://www.w3.org/TR/webauthn/#up"/>
+    /// <see href="https://www.w3.org/TR/webauthn/#up"/>
     /// </summary>
     UP = 0x1,
 
@@ -22,7 +22,7 @@ public enum AuthenticatorFlags : byte
 
     /// <summary>
     /// User Verified indicates that the user verification process has completed successfully.
-    /// <see cref="https://www.w3.org/TR/webauthn/#uv"/>
+    /// <see href="https://www.w3.org/TR/webauthn/#uv"/>
     /// </summary>
     UV = 0x4,
 
@@ -31,14 +31,14 @@ public enum AuthenticatorFlags : byte
     /// Backup eligibility is signaled in authenticator data's flags along with the current backup state. 
     /// Backup eligibility is a credential property and is permanent for a given public key credential source. 
     /// A backup eligible public key credential source is referred to as a multi-device credential whereas one that is not backup eligible is referred to as a single-device credential.
-    /// <see cref="https://w3c.github.io/webauthn/#backup-eligibility"/>
+    /// <see href="https://w3c.github.io/webauthn/#backup-eligibility"/>
     /// </summary>
     BE = 0x8,
 
     /// <summary>
     /// The current backup state of a multi-device credential as determined by the current managing authenticator. 
     /// Backup state is signaled in authenticator data's flags and can change over time.
-    /// <see cref="https://w3c.github.io/webauthn/#backup-state"/>
+    /// <see href="https://w3c.github.io/webauthn/#backup-state"/>
     /// </summary>
     BS = 0x10,
 
@@ -49,13 +49,13 @@ public enum AuthenticatorFlags : byte
 
     /// <summary>
     /// Attested credential data included indicates that the authenticator added attested credential data to the authenticator data.
-    /// <see cref="https://www.w3.org/TR/webauthn/#attested-credential-data"/>
+    /// <see href="https://www.w3.org/TR/webauthn/#attested-credential-data"/>
     /// </summary>
     AT = 0x40,
 
     /// <summary>
     /// Extension data included indicates that the authenticator added extension data to the authenticator data.
-    /// <see cref="https://www.w3.org/TR/webauthn/#authdataextensions"/>
+    /// <see href="https://www.w3.org/TR/webauthn/#authdataextensions"/>
     /// </summary>
     ED = 0x80,
 }

Src/Fido2/Objects/DevicePublicKeyAuthenticatorOutput.cs

@@ -35,14 +35,14 @@ internal DevicePublicKeyAuthenticatorOutput(CborMap map)
 
     /// <summary>
     /// The AAGUID of the authenticator. Can be used to identify the make and model of the authenticator.
-    /// <see cref="https://www.w3.org/TR/webauthn/#aaguid"/>
+    /// <see href="https://www.w3.org/TR/webauthn/#aaguid"/>
     /// </summary>
     public Guid AaGuid { get; }
 
     /// <summary>
     /// The credential public key encoded in COSE_Key format, as defined in 
     /// Section 7 of RFC8152, using the CTAP2 canonical CBOR encoding form.
-    /// <see cref="https://www.w3.org/TR/webauthn/#credential-public-key"/>
+    /// <see href="https://www.w3.org/TR/webauthn/#credential-public-key"/>
     /// </summary>
     public CredentialPublicKey DevicePublicKey { get; }
 
@@ -65,7 +65,7 @@ internal DevicePublicKeyAuthenticatorOutput(CborMap map)
 
     /// <summary>
     /// Attestation statement formats are identified by a string, called an attestation statement format identifier, chosen by the author of the attestation statement format.
-    /// <see cref="https://w3c.github.io/webauthn/#sctn-attstn-fmt-ids"/>
+    /// <see href="https://w3c.github.io/webauthn/#sctn-attstn-fmt-ids"/>
     /// </summary>
     public string Fmt { get; }
 

Src/Fido2/Objects/Extensions.cs

@@ -3,7 +3,7 @@
 namespace Fido2NetLib.Objects;
 
 /// <summary>
-/// <see cref="https://www.w3.org/TR/webauthn/#extensions"/>
+/// <see href="https://www.w3.org/TR/webauthn/#extensions"/>
 /// </summary>
 public sealed class Extensions
 {