Skip to content

Commit

Permalink
Generate XML documentation file (#502)
Browse files Browse the repository at this point in the history
  • Loading branch information
joegoldman2 authored Feb 16, 2024
1 parent b597d18 commit 274e7a8
Show file tree
Hide file tree
Showing 11 changed files with 51 additions and 29 deletions.
6 changes: 6 additions & 0 deletions Directory.Build.props
Original file line number Diff line number Diff line change
Expand Up @@ -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-->
Expand Down
2 changes: 1 addition & 1 deletion Src/Fido2.AspNet/Fido2NetLibBuilderExtensions.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
6 changes: 5 additions & 1 deletion Src/Fido2/AuthenticatorAssertionResponse.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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>
Expand Down
5 changes: 4 additions & 1 deletion Src/Fido2/AuthenticatorAttestationResponse.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
16 changes: 12 additions & 4 deletions Src/Fido2/Fido2.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand All @@ -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,
Expand All @@ -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,
Expand Down Expand Up @@ -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,
Expand Down
1 change: 1 addition & 0 deletions Src/Fido2/IMetadataService.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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);

Expand Down
8 changes: 4 additions & 4 deletions Src/Fido2/Objects/AttestedCredentialData.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand All @@ -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; }

Expand Down
14 changes: 7 additions & 7 deletions Src/Fido2/Objects/AuthenticatorData.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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);

Expand Down Expand Up @@ -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);

Expand All @@ -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);
Expand Down
14 changes: 7 additions & 7 deletions Src/Fido2/Objects/AuthenticatorFlags.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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,

Expand All @@ -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,

Expand All @@ -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,

Expand All @@ -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,
}
6 changes: 3 additions & 3 deletions Src/Fido2/Objects/DevicePublicKeyAuthenticatorOutput.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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; }

Expand All @@ -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; }

Expand Down
2 changes: 1 addition & 1 deletion Src/Fido2/Objects/Extensions.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand Down

0 comments on commit 274e7a8

Please sign in to comment.