Merge pull request #165

Docs/1.12 updates

Author: DennisDyallo

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

@@ -16,6 +16,41 @@ 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.0
+
+Release date: December 18th, 2024
+
+Features:
+
+- Security Domain application and Secure Channel Protocol (SCP) ([#164](https://github.com/Yubico/Yubico.NET.SDK/pull/164)):
+
+   - SCP11a/b/c is now supported for the PIV, OATH, OTP, and YubiHSM applications.
+   - SCP03 support has been extended to the OATH, OTP, and YubiHSM applications (previously PIV only).
+   - The Yubico.YubiKey.Scp namespace now provides all SCP and Security Domain functionality. This namepace replaces functionality in the Yubico.YubiKey.Scp03 namespace, which has been deprecated.
+   - The new `SecurityDomainSession` class provides an interface for managing the Security Domain application of a YubiKey. This includes SCP configuration (managing SCP03 key sets and SCP11 asymmetric keys and certificates) and creation of an encrypted communication channel with other YubiKey applications.
+   - New key parameter classes have been added: `ScpKeyParameters`, `Scp03KeyParameters`, `Scp11KeyParameters`, `ECKeyParameters`, `ECPrivateKeyParameters`, `ECPublicKeyParameters`.
+- [YubiKeyDeviceListener](xref:Yubico.YubiKey.YubiKeyDeviceListener) has been reconfigured to run the listeners in the background instead of the main thread. In addition, the listeners can now be [stopped](xref:Yubico.YubiKey.YubiKeyDeviceListener.StopListening) when needed to reclaim resources. Once stopped, the listeners can be restarted. ([#89](https://github.com/Yubico/Yubico.NET.SDK/pull/89))
+- Microsoft.Extensions.Logging.Console is now the default logger. To enable logging from a dependent project (e.g. unit tests, integration tests, an app), you can either add an appsettings.json to your project or use the ConfigureLoggerFactory. ([#139](https://github.com/Yubico/Yubico.NET.SDK/pull/139))
+- The SDK now uses inferred variable types (var) instead of explicit types in all projects except Yubico.Core. This change aims to improve code readability, reduce verbosity, and enhance developer productivity while maintaining type safety. ([#141](https://github.com/Yubico/Yubico.NET.SDK/pull/141))
+
+Bug Fixes:
+
+- The [PivSession.ChangeManagementKey](xref:Yubico.YubiKey.Piv.PivSession.ChangeManagementKey(Yubico.YubiKey.Piv.PivTouchPolicy)) method was incorrectly assuming Triple-DES was the default management key algorithm for FIPS keys. The SDK now verifies the management key alorithm based on key type and firmware version. ([#162](https://github.com/Yubico/Yubico.NET.SDK/pull/162))
+- The SDK now correctly sets the IYubiKeyDeviceInfo property [IsSkySeries](xref:Yubico.YubiKey.IYubiKeyDeviceInfo.IsSkySeries) to True for YubiKey Security Key Series Enterprise Edition keys. ([#158](https://github.com/Yubico/Yubico.NET.SDK/pull/158))
+- Exceptions are now caught when running [PivSession.Dispose](xref:Yubico.YubiKey.Piv.PivSession.Dispose). This fixes an issue where the Dispose method could not close the Connection in the event of a disconnected YubiKey. ([#104](https://github.com/Yubico/Yubico.NET.SDK/issues/104))
+- A dynamic DLL resolution based on process architecture (x86/x64) has been implemented for NativeShims.dll. This fixes a reported issue with the NativeShims.dll location for 32-bit processes. ([#154](https://github.com/Yubico/Yubico.NET.SDK/pull/154))
+
+Deprecations:
+
+- Yubico.YubiKey/Scp03 namespace.
+- All Yubico.Yubikey.StaticKeys endpoints.
+
+Migration Notes:
+- Use the `SecurityDomainSession` for Security Domain operations.
+- Review your logging configuration if using custom logging.
+- Align with Android/Python SDK naming conventions.
+
 ## 1.11.x Releases
 ### 1.11.0
 

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

@@ -38,7 +38,7 @@ namespace Yubico.YubiKey.Piv.Commands
     /// information on how to use this authentication.
     /// </para>
     /// <para>
-    /// Upon manufacture of a YubiKey, the management key is a Triple-DES key and
+    /// Upon manufacture of a YubiKey, the management key is either a Triple-DES key (firmware prior to 5.7) or an AES-192 key (firmware 5.7 and later), and
     /// it starts out as a default value:
     /// </para>
     /// <code>

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

@@ -300,7 +300,7 @@ private bool TryAuthenticateWithKeyCollector(bool mutualAuthentication)
         /// </remarks>
         /// <exception cref="InvalidOperationException">
         /// There is no <c>KeyCollector</c> loaded, the key provided was not a
-        /// valid Triple-DES key, or the YubiKey had some other error, such as
+        /// valid Triple-DES or AES key, or the YubiKey had some other error, such as
         /// unreliable connection.
         /// </exception>
         /// <exception cref="MalformedYubiKeyResponseException">
@@ -399,7 +399,7 @@ public void AuthenticateManagementKey(bool mutualAuthentication = true)
         /// <c>false</c> if it does not.
         /// </returns>
         /// <exception cref="InvalidOperationException">
-        /// The key provided was not a valid Triple-DES key, or the YubiKey had
+        /// The key provided was not a valid Triple-DES or AES key, or the YubiKey had
         /// some other error, such as unreliable connection.
         /// </exception>
         /// <exception cref="MalformedYubiKeyResponseException">
@@ -418,8 +418,7 @@ public bool TryAuthenticateManagementKey(ReadOnlyMemory<byte> managementKey, boo
         }
 
         /// <summary>
-        /// Try to change the management key. This will assume the new key is to
-        /// be Triple-DES.
+        /// Try to change the management key. The default management key algorithm will be used. (Firmware 5.7.x and later: AES-192. Firmware 5.6.x and earlier: TDES.)
         /// </summary>
         /// <remarks>
         /// Upon manufacture of a YubiKey, the PIV application begins with a
@@ -525,7 +524,7 @@ public bool TryAuthenticateManagementKey(ReadOnlyMemory<byte> managementKey, boo
         /// </returns>
         /// <exception cref="InvalidOperationException">
         /// There is no <c>KeyCollector</c> loaded, one of the keys provided was
-        /// not a valid Triple-DES key, or the YubiKey had some other error, such
+        /// not a valid Triple-DES  or AES key, or the YubiKey had some other error, such
         /// as unreliable connection.
         /// </exception>
         /// <exception cref="MalformedYubiKeyResponseException">
@@ -704,8 +703,8 @@ public bool TryChangeManagementKey(PivTouchPolicy touchPolicy, PivAlgorithm newK
         }
 
         /// <summary>
-        /// Change the management key, throw an exception if the user cancels.
-        /// The new key will be Triple-DES.
+        /// Change the management key, throw an exception if the user cancels. 
+        /// The default management key algorithm will be used. (Firmware 5.7.x and later: AES-192. Firmware 5.6.x and earlier: TDES.)
         /// </summary>
         /// <remarks>
         /// This is the same as <c>TryChangeManagementKey(PivTouchPolicy)</c>,
@@ -718,7 +717,7 @@ public bool TryChangeManagementKey(PivTouchPolicy touchPolicy, PivAlgorithm newK
         /// </remarks>
         /// <exception cref="InvalidOperationException">
         /// There is no <c>KeyCollector</c> loaded, the key provided was not a
-        /// valid Triple-DES key, or the YubiKey had some other error, such as
+        /// valid Triple-DES or AES key, or the YubiKey had some other error, such as
         /// unreliable connection.
         /// </exception>
         /// <exception cref="MalformedYubiKeyResponseException">
@@ -752,7 +751,7 @@ public void ChangeManagementKey(PivTouchPolicy touchPolicy = PivTouchPolicy.Defa
         /// </remarks>
         /// <exception cref="InvalidOperationException">
         /// There is no <c>KeyCollector</c> loaded, the key provided was not a
-        /// valid Triple-DES key, or the YubiKey had some other error, such as
+        /// valid Triple-DES or AES key, or the YubiKey had some other error, such as
         /// unreliable connection.
         /// </exception>
         /// <exception cref="MalformedYubiKeyResponseException">
@@ -783,8 +782,7 @@ public void ChangeManagementKey(PivTouchPolicy touchPolicy, PivAlgorithm newKeyA
 
         /// <summary>
         /// Try to change the management key. This method will use the
-        /// <c>currentKey</c> and <c>newKey</c> provided. The new key's algorithm
-        /// will be Triple-DES.
+        /// <c>currentKey</c> and <c>newKey</c> provided.
         /// </summary>
         /// <remarks>
         /// Normally, an application would call the
@@ -821,7 +819,7 @@ public void ChangeManagementKey(PivTouchPolicy touchPolicy, PivAlgorithm newKeyA
         /// if not.
         /// </returns>
         /// <exception cref="InvalidOperationException">
-        /// One of the keys provided was not a valid Triple-DES key, or the
+        /// One of the keys provided was not a valid Triple-DES or AES key, or the
         /// YubiKey had some other error, such as unreliable connection.
         /// </exception>
         /// <exception cref="MalformedYubiKeyResponseException">
@@ -883,7 +881,7 @@ public bool TryChangeManagementKey(ReadOnlyMemory<byte> currentKey,
         /// if not.
         /// </returns>
         /// <exception cref="InvalidOperationException">
-        /// One of the keys provided was not a valid Triple-DES key, or the
+        /// One of the keys provided was not a valid Triple-DES or AES key, or the
         /// YubiKey had some other error, such as unreliable connection.
         /// </exception>
         /// <exception cref="MalformedYubiKeyResponseException">

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

@@ -513,14 +513,14 @@ private PivPinOnlyMode GetPinDerivedStatus(
 
         /// <summary>
         ///     Set the YubiKey's PIV application to be PIN-only with a PIN-derived
-        ///     and/or PIN-Protected Triple-DES management key . This sets the
+        ///     and/or PIN-Protected Triple-DES management key. This sets the
         ///     YubiKey to either
         ///     <code>
-        ///   PivPinOnlyMode.PinProtected
-        ///   PivPinOnlyMode.PinDerived
-        ///   PivPinOnlyMode.PinProtected | PivPinOnlyMode.PinDerived
-        ///   PivPinOnlyMode.None
-        /// </code>
+        ///        PivPinOnlyMode.PinProtected
+        ///        PivPinOnlyMode.PinDerived
+        ///        PivPinOnlyMode.PinProtected | PivPinOnlyMode.PinDerived
+        ///        PivPinOnlyMode.None
+        ///     </code>
         ///     If the YubiKey is set to PinProtected, PinDerived, or both, the PUK
         ///     will also be blocked.
         ///     &gt; [!WARNING]
@@ -573,11 +573,11 @@ private PivPinOnlyMode GetPinDerivedStatus(
         ///     and/or PIN-Protected management key of the specified algorithm. This
         ///     sets the YubiKey to either
         ///     <code>
-        ///   PivPinOnlyMode.PinProtected
-        ///   PivPinOnlyMode.PinDerived
-        ///   PivPinOnlyMode.PinProtected | PivPinOnlyMode.PinDerived
-        ///   PivPinOnlyMode.None
-        /// </code>
+        ///        PivPinOnlyMode.PinProtected
+        ///        PivPinOnlyMode.PinDerived
+        ///        PivPinOnlyMode.PinProtected | PivPinOnlyMode.PinDerived
+        ///        PivPinOnlyMode.None
+        ///     </code>
         ///     If the YubiKey is set to PinProtected, PinDerived, or both, the PUK
         ///     will also be blocked.
         ///     &gt; [!WARNING]

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

@@ -139,8 +139,8 @@ namespace Yubico.YubiKey.Piv
     ///         <xref href="UsersManualSensitive"> sensitive data</xref>.
     ///     </para>
     ///     <para>
-    ///         This class will also need a random number generator and a Triple-DES
-    ///         encryptor/decryptor. It will get them from
+    ///         This class will also need a random number generator and Triple-DES and AES
+    ///         encryptors/decryptors. It will get them from
     ///         <see cref="CryptographyProviders" />. That class will return default
     ///         implementations, unless you replace them. Very few applications will
     ///         choose to replace the defaults, but if you want to, see the documentation