docs: New docs covering YubiKey Bio MPE quirks and special considerations (#237)

equijano21 · web-flow · commit f95871a58752 · 2025-06-09T09:10:51.000+02:00
* devicereset method

* more bio mpe reset docs

* changed setup chapter image sizes

* more bio mpe content, reset info clarification

* added intro paragraph

* added notes on MPE reset to FIDO user manual pages

* more fido reset edits

* added info to deviceresetcommand docs

* updated relevant PIV docs in user manual nad API guide
diff --git a/Yubico.YubiKey/src/Yubico/YubiKey/Management/Commands/DeviceResetCommand.cs b/Yubico.YubiKey/src/Yubico/YubiKey/Management/Commands/DeviceResetCommand.cs
@@ -17,10 +17,18 @@
 namespace Yubico.YubiKey.Management.Commands
 {
     /// <summary>
-    /// Execute device reset.
+    /// Execute the device-wide reset. 
     /// </summary>
     /// <remarks>
+    /// <para>
+    /// Resets ALL YubiKey applications (including FIDO and PIV) on the key to factory settings. This type of reset is only available on YubiKey Bio Multi-protocol Edition keys.
+    /// </para>
+    /// <para>
+    /// A reset will delete all FIDO2 credentials, fingerprints, and associated information, remove the shared PIN, delete all PIV keys and certificates from PIV slots (except the F9 attestation slot), remove any information added to the PIV data elements, and set the PIV PUK and management key back to their factory default states.
+    /// </para>
+    /// <para>
     /// This class has a corresponding partner class <see cref="DeviceResetResponse"/>
+    /// </para>
     /// </remarks>
     public class DeviceResetCommand : IYubiKeyCommand<DeviceResetResponse>
     {
diff --git a/Yubico.YubiKey/src/Yubico/YubiKey/Piv/Commands/ChangeReferenceDataCommand.cs b/Yubico.YubiKey/src/Yubico/YubiKey/Piv/Commands/ChangeReferenceDataCommand.cs
@@ -77,6 +77,9 @@ namespace Yubico.YubiKey.Piv.Commands
     ///   CryptographicOperations.ZeroMemory(puk);
     ///   CryptographicOperations.ZeroMemory(newPuk);
     /// </code>
+    /// <para>
+    /// Note: YubiKey Bio Multi-protocol Edition (MPE) keys do not have a PUK. 
+    /// </para>
     /// </remarks>
     public sealed class ChangeReferenceDataCommand : IYubiKeyCommand<ChangeReferenceDataResponse>
     {
diff --git a/Yubico.YubiKey/src/Yubico/YubiKey/Piv/Commands/ResetPivCommand.cs b/Yubico.YubiKey/src/Yubico/YubiKey/Piv/Commands/ResetPivCommand.cs
@@ -17,7 +17,7 @@
 namespace Yubico.YubiKey.Piv.Commands
 {
     /// <summary>
-    /// Reset the YubiKey's PIV application
+    /// Reset the YubiKey's PIV application.
     /// </summary>
     /// <remarks>
     /// The partner Response class is <see cref="ResetPivResponse"/>.
@@ -63,6 +63,9 @@ namespace Yubico.YubiKey.Piv.Commands
     ///       // Handle error
     ///   }
     /// </code>
+    /// <para>
+    /// This command does not work with YubiKey Bio Multi-protocol Edition (MPE) keys. For MPE keys, use <see cref="Yubico.YubiKey.Management.Commands.DeviceResetCommand"/> instead.
+    /// </para>
     /// </remarks>
     public sealed class ResetPivCommand : IYubiKeyCommand<ResetPivResponse>
     {
diff --git a/Yubico.YubiKey/src/Yubico/YubiKey/Piv/Commands/ResetRetryCommand.cs b/Yubico.YubiKey/src/Yubico/YubiKey/Piv/Commands/ResetRetryCommand.cs
@@ -85,6 +85,9 @@ namespace Yubico.YubiKey.Piv.Commands
     ///   CryptographicOperations.ZeroMemory(puk);
     ///   CryptographicOperations.ZeroMemory(newPin);
     /// </code>
+    /// <para>
+    /// Note: YubiKey Bio Multi-protocol Edition (MPE) keys do not have a PUK. 
+    /// </para>
     /// </remarks>
     public sealed class ResetRetryCommand : IYubiKeyCommand<ResetRetryResponse>
     {
diff --git a/Yubico.YubiKey/src/Yubico/YubiKey/Piv/PivSession.Pin.cs b/Yubico.YubiKey/src/Yubico/YubiKey/Piv/PivSession.Pin.cs
@@ -922,6 +922,9 @@ public bool TryChangePuk()
         /// See the <see cref="TryChangePuk()"/> method for further documentation
         /// on this method.
         /// </para>
+        /// <para>
+        /// Note: YubiKey Bio Multi-protocol Edition (MPE) keys do not have a PUK. 
+        /// </para>
         /// </remarks>
         /// <exception cref="InvalidOperationException">
         /// There is no <c>KeyCollector</c> loaded, or the YubiKey had some other
@@ -1140,9 +1143,12 @@ public bool TryResetPin()
         /// on this method.
         /// </para>
         /// <para>
-        /// If the PUK is blocked, this method will not execute. Note that if a
+        /// If the PUK is blocked, this method will not execute. If a
         /// YubiKey is configured PIN-only, the PUK will be blocked.
         /// </para>
+        /// <para>
+        /// Note: YubiKey Bio Multi-protocol Edition (MPE) keys do not have a PUK. 
+        /// </para>
         /// </remarks>
         /// <exception cref="InvalidOperationException">
         /// There is no <c>KeyCollector</c> loaded, or the YubiKey had some other
diff --git a/Yubico.YubiKey/src/Yubico/YubiKey/Piv/PivSession.cs b/Yubico.YubiKey/src/Yubico/YubiKey/Piv/PivSession.cs
@@ -364,7 +364,7 @@ public PivBioMetadata GetBioMetadata()
         ///         PUK, then call on the YubiKey to reset.
         ///     </para>
         ///     <para>
-        ///         Before attempting to reset a YubiKey Bio Multi-protocol Edition key with ResetApplication(), verify that the PIV application is not blocked from using this method by checking the <see cref="IYubiKeyDeviceInfo.ResetBlocked"/> property. If the application is blocked, use <see cref="IYubiKeyDevice.DeviceReset"/>.
+        ///         This method does not work with YubiKey Bio Multi-protocol Edition (MPE) keys. For MPE keys, use <see cref="IYubiKeyDevice.DeviceReset"/> instead.
         ///     </para>
         /// </remarks>
         /// <exception cref="SecurityException">
diff --git a/docs/users-manual/application-fido2/apdu/reset.md b/docs/users-manual/application-fido2/apdu/reset.md
@@ -12,7 +12,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License. -->
 
-## Get the next assertion
+## Reset the FIDO application
 
 ### Command APDU info
 
@@ -28,6 +28,9 @@ The data consists of the CTAP Command Byte and the CBOR encoding of the
 command's parameters. In this case, the CTAP Command Byte is `07`,
 which is the command "`authenticatorReset`". There are no command parameters.
 
+> [!NOTE]
+> The FIDO reset command APDU can be used with YubiKey Bio Multi-protocol Edition keys *only if* the FIDO application is not "blocked" (check the key's [ResetBlocked](xref:Yubico.YubiKey.YubiKeyDevice.ResetBlocked) property to confirm). Otherwise, the [device-wide reset](xref:UsersManualBioMpe#resetting-a-yubikey-bio-mpe) must be used instead. 
+
 ### Response APDU info
 
 #### Response APDU for a successful reset
diff --git a/docs/users-manual/application-fido2/fido2-commands.md b/docs/users-manual/application-fido2/fido2-commands.md
@@ -626,6 +626,9 @@ presence (touch).
 
 All YubiKeys with the FIDO2 application.
 
+> [!NOTE]
+> The FIDO2 ResetCommand can be used with YubiKey Bio Multi-protocol Edition keys *only if* the FIDO application is not "blocked" (check the key's [ResetBlocked](xref:Yubico.YubiKey.YubiKeyDevice.ResetBlocked) property to confirm). Otherwise, the [device-wide reset](xref:UsersManualBioMpe#resetting-a-yubikey-bio-mpe) must be used instead. 
+
 ### SDK classes
 
 [ResetCommand](xref:Yubico.YubiKey.Fido2.Commands.ResetCommand)
diff --git a/docs/users-manual/application-fido2/fido2-reset.md b/docs/users-manual/application-fido2/fido2-reset.md
@@ -29,6 +29,9 @@ However, there are some caveats:
   higer-level `Fido2Session` method for performing the entire operation. Instead, you must
   send a series of lower-level commands described below.
 
+> [!NOTE]
+> The individual FIDO reset can be used with YubiKey Bio Multi-protocol Edition keys *only if* the FIDO application is not "blocked" (check the key's [ResetBlocked](xref:Yubico.YubiKey.YubiKeyDevice.ResetBlocked) property to confirm). Otherwise, the [device-wide reset](xref:UsersManualBioMpe#resetting-a-yubikey-bio-mpe) must be used instead. 
+
 ## Steps
 
 Resetting the FIDO2 application is something you hope you never need to do. Generally, the
diff --git a/docs/users-manual/application-piv/apdu/change-ref.md b/docs/users-manual/application-piv/apdu/change-ref.md
@@ -36,6 +36,9 @@ The PIN can be composed of any ASCII character, but PUK composition depends on t
 The data is therefore 16 bytes, current value (possibly padded) followed by the new
 value (possibly padded).
 
+> [!NOTE]
+> YubiKey Bio Multi-protocol Edition (MPE) keys [do not have a PUK](xref:UsersManualBioMpe). 
+
 ### Response APDU Info
 
 #### Response APDU for CHANGE REFERENCE DATA (success)
diff --git a/docs/users-manual/application-piv/apdu/reset-piv.md b/docs/users-manual/application-piv/apdu/reset-piv.md
@@ -14,6 +14,8 @@ limitations under the License. -->
 
 ## Reset the PIV application
 
+Available for all YubiKeys with the PIV application except for YubiKey Bio Multi-protocol Edition (MPE) keys. For YubiKey Bio MPE, use the [device-wide reset](xref:UsersManualBioMpe#resetting-a-yubikey-bio-mpe) instead. 
+
 ### Command APDU Info
 
 | CLA | INS | P1 | P2 |    Lc    |   Data   |    Le    |
diff --git a/docs/users-manual/application-piv/apdu/reset-retry.md b/docs/users-manual/application-piv/apdu/reset-retry.md
@@ -14,6 +14,8 @@ limitations under the License. -->
 
 ## Reset retry (recover the PIN)
 
+Available for all YubiKeys with the PIV application except for YubiKey Bio Multi-protocol Edition (MPE) keys, which [do not have a PUK](xref:UsersManualBioMpe). 
+
 ### Command APDU Info
 
 | CLA | INS | P1 | P2 | Lc |           Data            |    Le    |
diff --git a/docs/users-manual/application-piv/commands.md b/docs/users-manual/application-piv/commands.md
@@ -568,7 +568,10 @@ only recovery is to [Reset the PIV application](#reset-the-piv-application).
 
 ### Available
 
-All YubiKeys with the PIV application.
+All YubiKeys with the PIV application. 
+
+> [!NOTE]
+> YubiKey Bio Multi-protocol Edition (MPE) keys [do not have a PUK](xref:UsersManualBioMpe). 
 
 ### SDK Classes
 
@@ -705,7 +708,7 @@ If the PUK is blocked, the only recovery is to
 
 ### Available
 
-All YubiKeys with the PIV application.
+All YubiKeys with the PIV application except for YubiKey Bio Multi-protocol Edition (MPE) keys, which [do not have a PUK](xref:UsersManualBioMpe). 
 
 ### SDK Classes
 
@@ -1636,7 +1639,7 @@ This command will be accepted only if the PIN and PUK are both blocked.
 
 ### Available
 
-All YubiKeys with the PIV application.
+All YubiKeys with the PIV application except for YubiKey Bio Multi-protocol Edition (MPE) keys. For YubiKey Bio MPE, use the [device-wide reset](xref:UsersManualBioMpe#resetting-a-yubikey-bio-mpe) instead. 
 
 ### SDK Classes
 
diff --git a/docs/users-manual/application-piv/pin-puk-mgmt-key.md b/docs/users-manual/application-piv/pin-puk-mgmt-key.md
@@ -125,6 +125,9 @@ deletes the keys in all PIV slots and resets the PIN, PUK, and management key to
 defaults. Note that this has no effect on the other YubiKey applications (OTP, FIDO,
 etc.).
 
+> [!NOTE]
+> ``PivSession.Reset()`` cannot be used with YubiKey Bio Multi-protocol Edition (MPE) keys — use the [device-wide reset](xref:UsersManualBioMpe#resetting-a-yubikey-bio-mpe) instead. YubiKey Bio MPE keys also do not have PUKs, so it is not possible to unblock a blocked PIN. See [YubiKey Bio Multi-protocol Edition considerations and quirks](xref:UsersManualBioMpe#) for more information. 
+
 The management key cannot be blocked. If an attacker wants to try to break your management
 key, they can try a brute-force attack (with a Triple-DES it is a modified brute-force
 attack), which means trying every possible key until "stumbling" onto the correct one.
diff --git a/docs/users-manual/sdk-programming-guide/bio-mpe.md b/docs/users-manual/sdk-programming-guide/bio-mpe.md
@@ -0,0 +1,123 @@
+---
+uid: UsersManualBioMpe
+---
+
+<!-- Copyright 2025 Yubico AB
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License. -->
+
+# YubiKey Bio Multi-protocol Edition considerations and quirks
+
+YubiKey Bio Multi-protocol Edition (MPE) keys possess some unique attributes that require special consideration when using the .NET YubiKey SDK compared to other YubiKeys with FIDO and PIV capabilities. This page details these differences and how to manage them.
+
+## Shared PIN, no PUK
+
+Typically, YubiKeys that have both the PIV and FIDO applications (like the 5 Series) have separate PIV and FIDO PINs. However, the YubiKey Bio MPE, which integrates fingerprint biometrics from the FIDO application with PIV functionality, uses a shared PIN for the FIDO and PIV applications. Use of the shared PIN results in two major changes:
+
+- The addition of a special [device-wide reset](#resetting-a-yubikey-bio-mpe), which resets both the FIDO and PIV applications simultaneously
+- The omission of the PIV [PUK](xref:UsersManualPinPukMgmtKey) (PIN Unblocking Key)
+
+No PUK means that once a YubiKey Bio MPE's PIN has been blocked, there is no way to unblock/change the PIN — the key must be reset. This also means that the SDK's [ResetRetryCommand](xref:UsersManualPivCommands#reset-retry-recover-the-pin) (used to reset the PIN using the PUK) will fail along with any attempt to change the nonexistent PUK with the [ChangeReferenceDataCommand](xref:UsersManualPivCommands#change-reference-data).
+
+## Resetting a YubiKey Bio MPE
+
+For all YubiKeys except for the YubiKey Bio MPE, factory resets are done strictly *by application*. For example, if you wanted to reset the PIV and FIDO applications on a YubiKey 5 Series key, you would need to perform both a [PIV reset](xref:Yubico.YubiKey.Piv.PivSession.ResetApplication) and a [FIDO reset](xref:Fido2Reset). 
+
+Under most circumstances, it is not possible to perform factory resets for the PIV and FIDO applications individually with the YubiKey Bio MPE. Instead, a special device-wide reset must be used, which resets both PIV and FIDO applications at the same time. This device-wide reset can be performed via the ``DeviceReset()`` method, the ``DeviceResetCommand()``, or by sending a command APDU with the device reset instruction. 
+
+> [!NOTE]
+> The individual FIDO reset can technically be used with YubiKey Bio MPE keys, but *only* if the FIDO application is not "blocked" (check the key's [ResetBlocked](xref:Yubico.YubiKey.YubiKeyDevice.ResetBlocked) property to confirm). The individual PIV reset cannot be used with YubiKey Bio MPE keys regardless of the PIV application's ``ResetBlocked`` status.
+
+### DeviceReset() method
+
+Using the [DeviceReset()](xref:Yubico.YubiKey.YubiKeyDevice.DeviceReset) method is simple: [connect](xref:UsersManualMakingAConnection) to a YubiKey with the [YubiKeyDevice](xref:Yubico.YubiKey.YubiKeyDevice) class, then call the method on that key.
+
+To select the first available YubiKey connected to your host, use:
+
+```C#
+IEnumerable<IYubiKeyDevice> yubiKeyList = YubiKeyDevice.FindAll();
+
+var yubiKey = yubiKeyList.First();
+```
+
+Then perform the reset:
+
+```C#
+yubiKey.DeviceReset();
+```
+
+### DeviceResetCommand() 
+
+The device-wide reset can also be performed using the lower-level [DeviceResetCommand](xref:Yubico.YubiKey.Management.Commands.DeviceResetCommand) and [DeviceResetResponse](xref:Yubico.YubiKey.Management.Commands.DeviceResetResponse) classes (which is what the ``DeviceReset()`` method implements under the hood). 
+
+After connecting to a particular YubiKey with the ``YubiKeyDevice`` class as shown in the previous example, we need to set up an additional connection to the key's management application using the [IYubiKeyConnection](xref:Yubico.YubiKey.IYubiKeyConnection) class:
+
+```C#
+IYubiKeyConnection connection = yubiKey.Connect(YubiKeyApplication.Management);
+```
+
+Then send the ``DeviceResetCommand`` to the key:
+
+```C#
+DeviceResetCommand resetCommand = new DeviceResetCommand();
+DeviceResetResponse resetResponse = connection.SendCommand(resetCommand);
+```
+
+For error handling, check the ``DeviceResetResponse`` instance's [Status](xref:Yubico.YubiKey.IYubiKeyResponse.Status) and [StatusMessage](xref:Yubico.YubiKey.IYubiKeyResponse.StatusMessage) properties. For general information on using the SDK's command classes, see [Commands](xref:UsersManualCommands).
+
+### DeviceReset APDUs
+
+At the lowest level, the device-wide reset can be performed by sending a command [APDU](xref:UsersManualApdu) to a YubiKey and handling its response APDU (which is what the ``DeviceResetCommand`` and ``DeviceResetResponse`` implement under the hood). 
+
+The command APDU is simple, requiring the instruction ``1F`` with no additional data. The response APDU returned from the key will only contain the status word.
+
+**Command APDU**:
+
+| CLA | INS | P1 | P2 |    Lc    |   Data   |    Le    |
+|:---:|:---:|:--:|:--:|:--------:|:--------:|:--------:| 
+| 00  | 1F  | 00 | 00 | (absent) | (absent) | (absent) |
+
+**Response APDU (success)**:
+
+Total Length: 2 bytes
+
+Data Length: 0
+
+|   Data    | SW1 | SW2 |
+|:---------:|:---:|:---:|
+| (no data) | 90  | 00  |
+
+**Response APDU (failure)**:
+
+Total Length: 2 bytes
+
+Data Length: 0
+
+|   Data    | SW1 | SW2 |
+|:---------:|:---:|:---:|
+| (no data) | 6f  | 00  |
+
+#### OpenSC example
+
+To perform the device reset on a YubiKey Bio MPE with a tool like [OpenSC](https://github.com/OpenSC/OpenSC), you must first send a command APDU to connect to the key's management application (``00a4040008a000000527471117``) followed by the device reset command APDU (``001F0000``):
+
+```text
+opensc-tool -c default -s 00a4040008a000000527471117 -s 001F0000
+Using reader with a card: Yubico YubiKey FIDO+CCID
+Sending: 00 A4 04 00 08 A0 00 00 05 27 47 11 17 
+Received (SW1=0x90, SW2=0x00):
+56 69 72 74 75 61 6C 20 6D 67 72 20 2D 20 46 57 Virtual mgr - FW
+20 76 65 72 73 69 6F 6E 20 35 2E 37 2E 32        version 5.7.2
+Sending: 00 1F 00 00 
+Received (SW1=0x90, SW2=0x00)
+```
diff --git a/docs/users-manual/toc.yml b/docs/users-manual/toc.yml
@@ -56,6 +56,8 @@
     href: sdk-programming-guide/device-notifications.md
   - name: PIN complexity policy
     href: sdk-programming-guide/pin-complexity-policy.md
+  - name: YubiKey Bio Multi-protocol Edition considerations and quirks
+    href: sdk-programming-guide/bio-mpe.md
   - name: Maintaining compatibility
     href: sdk-programming-guide/appcompat.md
 
