Merge pull request #181 from Yubico/merge/release/1.12.1

Release 1.12.1

Author: DennisDyallo

README.md

@@ -1,4 +1,4 @@
-<!-- Copyright 2021 Yubico AB
+<!-- Copyright 2024 Yubico AB
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -21,42 +21,101 @@ limitations under the License. -->
 
 # .NET YubiKey SDK
 
-This is a cross-platform, all encompassing SDK for the YubiKey aimed at large to mid-sized enterprise
-customers. This version is written against .NET Core, and will eventually include bindings to languages
-outside the direct .NET ecosystem.
+Enterprise-grade cross-platform SDK for YubiKey integration, built on .NET.
 
-## SDK Support
-The SDK is targetting net47, netstandard2.0 and netstandard2.1. This means the SDK can be loaded in NET Framework, NET6 and upwards.
+## Table of Contents
+- [Quick Start](#quick-start)
+- [Documentation](#documentation)
+- [SDK Support](#sdk-support)
+- [SDK Packages](#sdk-packages)
+- [Project Structure](#project-structure)
+- [Contributing](#contributing)
+- [Security](#security)
+
+## Quick Start
+
+### Installation
+```bash
+dotnet add package Yubico.YubiKey
+```
+
+### Basic Usage
+```csharp
+using Yubico.YubiKey;
+
+// Chooses the first YubiKey found on the computer.
+IYubiKeyDevice? SampleChooseYubiKey()
+{
+    IEnumerable<IYubiKeyDevice> list = YubiKeyDevice.FindAll();
+    return list.First();
+}
+```
 
 ## Documentation
 
-The public documentation for this project is located
-at [https://docs.yubico.com/yesdk/](https://docs.yubico.com/yesdk/).
-Here you can find both API reference and a user's manual that describes the concepts that this SDK exposes.
+📚 Official documentation: [docs.yubico.com/yesdk](https://docs.yubico.com/yesdk/)
+- User Manual
+- API Reference
+
+## SDK Support
+
+Supported Target Frameworks:
+- .NET Framework 4.7
+- .NET Standard 2.1
+- .NET 6 and above
 
-## Project structure
+## SDK Packages
 
-The root of this repository contains the various projects that make up the SDK. Inside each project
-folder, you will find:
+### Public Assemblies
 
-- docs - Supplementary documentation content for the SDK's API documentation.
-- examples - Example code demonstrating various capabilities of the SDK.
-- src - All source code that makes up the project.
-- tests - Unit and integration tests for the project.
+#### Yubico.YubiKey
+Primary assembly containing all classes and types needed for YubiKey interaction.
+
+#### Yubico.Core
+Platform abstraction layer (PAL) providing:
+- OS-specific functionality abstraction
+- Device enumeration
+- Utility classes for various encoding/decoding operations:
+  - Base16
+  - Base32
+  - Tag-Length-Value (BER Encoded TLV)
+  - ModHex
+
+### Internal Assemblies
+
+#### Yubico.DotNetPolyfills
+> ⚠️ **Not for public use**  
+> Backports BCL features needed by the SDK.
+
+#### Yubico.NativeShims
+> ⚠️ **Not for public use**  
+> 🔧 **Unmanaged Library**  
+> Provides stable ABI for P/Invoke operations in Yubico.Core.
+
+## Project Structure
+
+Repository organization:
+- 📁 `docs/` - API documentation and supplementary content
+- 📁 `examples/` - Sample code and demonstrations
+- 📁 `src/` - Source code for all projects
+- 📁 `tests/` - Unit and integration tests
 
 ## Contributing
 
-Please read the [Contributor's Guide](./CONTRIBUTING.md) and [Getting started](./contributordocs/getting-started.md)
-pages before opening a pull request on this project.
+1. Read the [Contributor's Guide](./CONTRIBUTING.md)
+2. Review [Getting Started](./contributordocs/getting-started.md)
+3. Submit your Pull Request
+
+### Building the Project
 
-### Building
+Prerequisites:
+1. Install required tools (see [Getting Started](./contributordocs/getting-started.md))
+2. Load `Yubico.NET.SDK.sln` into your IDE.
+3. Build solution
 
-Read the [Getting started](./contributordocs/getting-started.md) page to understand the prerequisites needed
-to build. Once those have been installed, you should be able to load the Yubico.NET.SDK.sln file and build.
+---
 
-Note that it is also possible to build the DocFX output at the same time as building the libraries. However,
-that is not done by default.
+## Connect with us
 
-If you want to build the DocFX output when you build the libraries using Visual Studio, open the Visual
-Studio solution file, and open `Build:Configuration Manager...`. In the resulting window, under
-`Active solution configuration:` is a drop-down menu. Select `ReleaseWithDocs`.
+📫 Need help? [Create an issue](https://github.com/Yubico/Yubico.NET.SDK/issues/new/choose)  
+📖 Read our blog for the latest Yubico updates [here](https://www.yubico.com/blog/)

Yubico.Core/src/Yubico.Core.csproj

@@ -41,6 +41,7 @@ limitations under the License. -->
       Yubico.Core is a support library used by other .NET Yubico libraries. You should likely never need to consume this package directly, as it will be included with other libraries.
     </Description>
     <PackageIcon>yubico-circle-y-mark.png</PackageIcon>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
     <PublishRepositoryUrl>true</PublishRepositoryUrl>
     <EmbedUntrackedSources>true</EmbedUntrackedSources>
     <IncludeSymbols>true</IncludeSymbols>
@@ -72,6 +73,7 @@ limitations under the License. -->
     </EmbeddedResource>
 
     <None Include="..\..\LICENSE.txt" Pack="true" PackagePath="" />
+    <None Include="..\..\README.md" Pack="true" PackagePath="" />
     <None Include="..\..\yubico-circle-y-mark.png" Pack="true" PackagePath="" />
     <None Include="..\..\Yubico.NET.SDK.snk">
       <Link>Yubico.NET.SDK.snk</Link>

Yubico.DotNetPolyfills/src/Yubico.DotNetPolyfills.csproj

@@ -30,6 +30,7 @@ limitations under the License. -->
 
     <PackageRequireLicenseAcceptance>true</PackageRequireLicenseAcceptance>
     <PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
     <PublishRepositoryUrl>true</PublishRepositoryUrl>
     <EmbedUntrackedSources>true</EmbedUntrackedSources>
     <IncludeSymbols>true</IncludeSymbols>
@@ -66,6 +67,7 @@ limitations under the License. -->
 
   <ItemGroup>
     <None Include="..\..\LICENSE.txt" Pack="true" PackagePath="" />
+    <None Include="..\..\README.md" Pack="true" PackagePath="" />
   </ItemGroup>
 
 </Project>

Yubico.YubiKey/docs/users-manual/getting-started/whats-new.md

@@ -17,6 +17,14 @@ limitations under the License. -->
 Here you can find all of the updates and release notes for published versions of the SDK.
 
 ## 1.12.x Releases
+
+### 1.12.1
+
+Release date: December 19th, 2024
+
+Bug Fixes: Now selects correct device initializing Fido2Session [(#179)](https://github.com/Yubico/Yubico.NET.SDK/pull/179)
+
+
 ### 1.12.0
 
 Release date: December 18th, 2024

Yubico.YubiKey/src/Yubico.YubiKey.csproj

@@ -41,6 +41,7 @@ limitations under the License. -->
       Yubico.YubiKey is the official .NET library for integrating with the YubiKey hardware authenticator. This library supports both macOS and Windows operating systems.
     </Description>
     <PackageIcon>yubico-circle-y-mark.png</PackageIcon>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
     <PublishRepositoryUrl>true</PublishRepositoryUrl>
     <EmbedUntrackedSources>true</EmbedUntrackedSources>
     <IncludeSymbols>true</IncludeSymbols>
@@ -100,8 +101,8 @@ limitations under the License. -->
       <LastGenOutput>ResponseStatusMessages.Designer.cs</LastGenOutput>
       <CustomToolNamespace>Yubico.YubiKey</CustomToolNamespace>
     </EmbeddedResource>
-
     <None Include="..\..\LICENSE.txt" Pack="true" PackagePath="" />
+    <None Include="..\..\README.md" Pack="true" PackagePath="" />
     <None Include="..\..\yubico-circle-y-mark.png" Pack="true" PackagePath="" />
     <None Include="..\..\Yubico.NET.SDK.snk">
       <Link>Yubico.NET.SDK.snk</Link>

Yubico.YubiKey/src/Yubico/YubiKey/ConnectionFactory.cs

@@ -112,14 +112,6 @@ public IScpYubiKeyConnection CreateScpConnection(YubiKeyApplication application,
         /// </remarks>
         public IYubiKeyConnection CreateConnection(YubiKeyApplication application)
         {
-            if (_smartCardDevice != null)
-            {
-                _log.LogDebug("Connecting via the SmartCard interface.");
-
-                WaitForReclaimTimeout(Transport.SmartCard);
-                return new SmartCardConnection(_smartCardDevice, application);
-            }
-
             if (_hidKeyboardDevice != null && application == YubiKeyApplication.Otp)
             {
                 _log.LogDebug("Connecting via the Keyboard interface.");
@@ -128,13 +120,22 @@ public IYubiKeyConnection CreateConnection(YubiKeyApplication application)
                 return new KeyboardConnection(_hidKeyboardDevice);
             }
 
-            if (_hidFidoDevice != null && (application == YubiKeyApplication.Fido2 || application == YubiKeyApplication.FidoU2f))
+            bool isFidoApplication = application == YubiKeyApplication.Fido2 || application == YubiKeyApplication.FidoU2f;
+            if (_hidFidoDevice != null && isFidoApplication)
             {
                 _log.LogDebug("Connecting via the FIDO interface.");
 
                 WaitForReclaimTimeout(Transport.HidFido);
                 return new FidoConnection(_hidFidoDevice);
             }
+            
+            if (_smartCardDevice != null)
+            {
+                _log.LogDebug("Connecting via the SmartCard interface.");
+
+                WaitForReclaimTimeout(Transport.SmartCard);
+                return new SmartCardConnection(_smartCardDevice, application);
+            }
 
             throw new InvalidOperationException("No suitable interface present. Unable to establish connection to YubiKey.");
         }

Yubico.YubiKey/src/Yubico/YubiKey/Oath/OathSession.cs

@@ -127,11 +127,9 @@ protected override void Dispose(bool disposing)
         {
             if (disposing)
             {
-                return;
+                KeyCollector = null;
+                base.Dispose(disposing);
             }
-
-            KeyCollector = null;
-            base.Dispose(disposing);
         }
     }
 }

Yubico.YubiKey/src/Yubico/YubiKey/Piv/Commands/InitializeAuthenticateManagementKeyCommand.cs

@@ -321,7 +321,7 @@ public InitializeAuthenticateManagementKeyCommand()
         /// <remarks>
         /// Using this constructor is equivalent to
         /// <code language="csharp">
-        ///  new InitializeAuthenticateManagementKeyCommand(true, PivAlgorithm.AES192);
+        ///  new InitializeAuthenticateManagementKeyCommand(true, PivAlgorithm.algorithm);
         /// </code>
         /// </remarks>
         public InitializeAuthenticateManagementKeyCommand(PivAlgorithm algorithm)

Yubico.YubiKey/src/Yubico/YubiKey/Piv/Commands/SetManagementKeyCommand.cs

@@ -137,7 +137,7 @@ public sealed class SetManagementKeyCommand : IYubiKeyCommand<SetManagementKeyRe
         /// 5.4.2, only Triple-DES (<c>PivAlgorithm.TripleDes</c>) is supported.
         /// Beginning with 5.4.2, the Algorithm can be <c>Aes128</c>,
         /// <c>Aes192</c>, <c>Aes256</c>, or <c>TripleDes</c>. The default is
-        /// <c>TripleDes</c>.
+        /// <c>TripleDes</c> for keys with firmware 5.6.x and earlier and <c>Aes192</c> for YubiKeys with firmware 5.7.x and later.
         /// </summary>
         public PivAlgorithm Algorithm { get; set; }
 
@@ -168,8 +168,7 @@ public SetManagementKeyCommand(ReadOnlyMemory<byte> newKey)
         /// <summary>
         /// Initializes a new instance of the <c>SetManagementKeyCommand</c> class.
         /// This command takes the new management key as input and will set the
-        /// <c>TouchPolicy</c> and <c>Algorithm</c> properties to their
-        /// respective defaults.
+        /// <c>TouchPolicy</c> to the default state and the <c>Algorithm</c> to the algorithm provided.
         /// </summary>
         /// <remarks>
         /// This constructor is provided for those developers who want to use the
@@ -184,7 +183,7 @@ public SetManagementKeyCommand(ReadOnlyMemory<byte> newKey)
         /// <para>
         /// Valid algorithms are <c>PivAlgorithm.TripleDes</c>,
         /// <c>PivAlgorithm.Aes128</c>, <c>PivAlgorithm.Aes192</c>, and
-        /// <c>PivAlgorithm.Aes256</c>. FIPS YubiKeys versions 5.7 and greater require <c>PivAlgorithm.Aes192</c>.
+        /// <c>PivAlgorithm.Aes256</c>. FIPS YubiKeys versions 5.7 and greater require <c>PivAlgorithm.Aes192</c>. YubiKeys with firmware versions prior to 5.4.2 can only use <c>PivAlgorithm.TripleDes</c>.
         /// </para>
         /// <para>
         /// Note that you need to authenticate the current PIV management key before
@@ -219,7 +218,7 @@ public SetManagementKeyCommand(ReadOnlyMemory<byte> newKey, PivTouchPolicy touch
         /// <para>
         /// Valid algorithms are <c>PivAlgorithm.TripleDes</c>,
         /// <c>PivAlgorithm.Aes128</c>, <c>PivAlgorithm.Aes192</c>, and
-        /// <c>PivAlgorithm.Aes256</c>. FIPS YubiKeys versions 5.7 and greater require <c>PivAlgorithm.Aes192</c>.
+        /// <c>PivAlgorithm.Aes256</c>. FIPS YubiKeys versions 5.7 and greater require <c>PivAlgorithm.Aes192</c>. YubiKeys with firmware versions prior to 5.4.2 can only use <c>PivAlgorithm.TripleDes</c>.
         /// </para>
         /// <para>
         /// Note also that you need to authenticate the current PIV management

Yubico.YubiKey/src/Yubico/YubiKey/Piv/PivSession.Pinonly.cs

@@ -513,7 +513,7 @@ private PivPinOnlyMode GetPinDerivedStatus(
 
         /// <summary>
         ///     Set the YubiKey's PIV application to be PIN-only with a PIN-derived
-        ///     and/or PIN-Protected management key (Firmware 5.7.x and later: AES-192. Firmware 5.6.x and earlier: TDES.). This sets the
+        ///     and/or PIN-Protected management key. The default management key algorithm will be used (AES-192 for YubiKeys with firmware 5.7.x and later, TDES for keys with firmware 5.6.x and earlier). This sets the
         ///     YubiKey to either
         ///     <code>
         ///        PivPinOnlyMode.PinProtected
@@ -727,7 +727,7 @@ private PivPinOnlyMode GetPinDerivedStatus(
         /// </param>
         /// <exception cref="InvalidOperationException">
         ///     There is no <c>KeyCollector</c> loaded, one of the keys provided was
-        ///     not of a valid key algorithm type (Firmware 5.7.x and later: AES-192. Firmware 5.6.x and earlier: TDES.), the data stored on the YubiKey is
+        ///     not of a valid key algorithm type, the data stored on the YubiKey is
         ///     incompatible with PIN-only, or the YubiKey had some other error, such
         ///     as unreliable connection.
         /// </exception>