Add PIV Bio extensions

Yubico.YubiKey/docs/users-manual/application-piv/apdu/bio-metadata.md

@@ -0,0 +1,47 @@
+---
+uid: UsersManualBioMetadata
+---
+
+<!-- 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.
+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. -->
+
+
+## Get bio metadata
+
+### Command APDU Info
+
+CLA | INS | P1 | P2 | Lc | Data | Le
+:---: | :---: | :---: | :---: | :---: | :---:
+00 | F7 | 00 | 96 | (absent) | (absent) | (absent)
+
+### Response APDU Info
+
+Total Length: *9* + 2\
+Data Length: *9*
+
+Data | SW1 | SW2
+:---: | :---: | :---:
+*bio metadata as set of TLV* | 90 | 00
+
+The data consists of a set of TLVs. The possible valid tags (T of TLV) are listed in the
+table below. The length (L of TLV) is one. The values (V of TLV) are dependent on the tags, 
+described in the table below.
+
+#### Table 1: List of Metadata Elements
+Tag | Name | Meaning | Data
+:---: | :---: | :---: | :---:
+07 | IsConfigured| state of biometric verification configuration<br/> (ie. fingerprints are enrolled) | 01 (configured)<br/> 00 (not configured)
+06 | RetriesRemaining| indicates how many biometric match retries are left| 00-03<br/>value 00 while IsConfigured is 01 indicates that biometric verification is blocked
+08 | HasTemporaryPin| indicates if a temporary PIN has been generated in the YubiKey | 01 (generated)<br/>00 (not generated)
+

Yubico.YubiKey/docs/users-manual/application-piv/apdu/verify-temporary-pin.md

@@ -0,0 +1,45 @@
+<!-- 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.
+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. -->
+
+
+## Verify temporary PIN
+
+### Command APDU info
+
+CLA | INS | P1 | P2 | Lc | Data | Le
+:---: | :---: | :---: | :---: | :---: | :---:
+00 | 20 | 00 | 96 | 12 | 01 10 *temporary PIN* | (absent)
+
+### Response APDU info
+
+#### Response APDU for VERIFY (success)
+
+Total Length: 2\
+Data Length: 0
+
+Data | SW1 | SW2
+:---: | :---: | :---:
+(no data) | 90 | 00
+
+#### Response APDU for VERIFY (Invalid temporary PIN)
+
+Total Length: 2\
+Data Length: 0
+
+Data | SW1 | SW2
+:---: | :---: | :---:
+(no data) | 63 | C0
+
+If the temporary PIN is incorrect, then the error is `63 C0`. The temporary PIN in invalidated in the YubiKey and a new one needs to be obtained.
+

Yubico.YubiKey/docs/users-manual/application-piv/apdu/verify-uv.md

@@ -0,0 +1,59 @@
+<!-- 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.
+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. -->
+
+
+## Verify UV 
+
+### Command APDU info
+
+CLA | INS | P1 | P2 | Lc | Data | Le
+:---: | :---: | :---: | :---: | :---: | :---:
+00 | 20 | 00 | 96 | *variable* | *variable* | (absent)
+
+The data bytes vary:
+- none  - for checking the biometric state
+- 02 00 - if temporary PIN has been requested
+- 03 00 - if biometric verification has been requested
+
+### Response APDU info
+
+#### Response APDU for VERIFY (success)
+
+Total Length: 2\
+Data Length: 0
+
+Data | SW1 | SW2
+:---: | :---: | :---:
+(no data) | 90 | 00
+
+#### Response APDU for VERIFY (success with temporary PIN)
+
+Total Length: 18\
+Data Length: 16
+
+Data | SW1 | SW2
+:---: | :---: | :---:
+temporary PIN | 90 | 00
+
+#### Response APDU for VERIFY (Invalid biometric match)
+
+Total Length: 2\
+Data Length: 0
+
+Data | SW1 | SW2
+:---: | :---: | :---:
+(no data) | 63 | C0 - C2
+
+If the biometric match failed, then the error is `63 CX` where *X* is the number of
+retries remaining. In the case of C0, the biometric verification becomes blocked.

Yubico.YubiKey/docs/users-manual/application-piv/commands.md

@@ -31,7 +31,9 @@ is the one calling the YubiKey. The keys, data, and firmware running on the Yubi
 * [Get the serial number](#get-the-serial-number)
 * [Get the firmware version number](#get-the-firmware-version-number)
 * [Get metadata](#get-metadata)
+* [Get Bio metadata](#get-bio-metadata)
 * [Verify the PIN](#verify)
+* [Biometric verification](#biometric-verification)
 * [Authenticate: management key](#authenticate-management-key)
 * [Set PIN retries](#set-pin-retries)
 * [Change reference data](#change-reference-data) (change the PIN or PUK)
@@ -172,6 +174,34 @@ elements are returned for each slot.
 
 [Technical APDU Details](apdu/metadata.md)
 ___
+## Get Bio metadata
+
+This gets YubiKey's biometric metadata. 
+
+### Available
+
+YubiKey Bio Multi-protocol 5.6 and later.
+
+### SDK Classes
+
+[GetBioMetadataCommand](xref:Yubico.YubiKey.Piv.Commands.GetBioMetadataCommand)
+
+[GetBioMetadataResponse](xref:Yubico.YubiKey.Piv.Commands.GetBioMetadataResponse)
+
+### Output
+
+#### Table 1: List of Metadata Elements
+|   Name            |                  Meaning                                 |                              Data                                 |
+| :---------------: | :------------------------------------------------------: | :---------------------------------------------------------------: |
+|  IsConfigured     |  Is this device configured for biometric verification    |  bool                                                             |
+|  RetriesRemaining |  Number of remaining retries for biometric verification  |  integer, zero value means the biometric verification is blocked  |
+|  HasTemporaryPin  |  Whether a temporary PIN is generated                    |  bool                                                             |
+
+
+### APDU
+
+[Technical APDU Details](apdu/bio-metadata.md)
+___
 ## Verify
 
 Verify a PIN.
@@ -259,6 +289,58 @@ value and `GetData` will throw an exception.
 
 [Technical APDU Details](apdu/verify.md)
 ___
+## Biometric verification
+
+With biometric verification, the users can authenticate the PIV session with a successful match of a fingerprint. To be able to execute the biometric verification, the YubiKey has to have biometrics configured and must not be blocked for using biometrics. Clients can verify the conditions by reading the properties of biometric metadata (see [Get Bio metadata](#get-bio-metadata)).
+
+The YubiKey keeps track of failed biometric matches and will block the biometric authentication if there are more than three such failures. In that case the client should use the PIN verification as soon as possible. The number of remaining biometric matches is returned in the command response's `AttemptsRemaining` property. The value is present only after a failed match.
+
+Clients can also request to generate a temporary PIN which can be used with the `VerifyTemporaryPinCommand` for authentication without the need of a biometric match. The temporary PIN is stored in YubiKey's RAM and is invalidated after the PIV session is closed or an attempt of using a wrong temporary PIN. For `PIN_OR_MATCH_ALWAYS` slot policy, the temporary PIN can be used only once.
+
+### Available
+
+YubiKey Bio Multi-Protocol keys.
+
+### SDK Classes
+
+[VerifyUvCommand](xref:Yubico.YubiKey.Piv.Commands.VerifyUvCommand)
+
+[VerifyUvResponse](xref:Yubico.YubiKey.Piv.Commands.VerifyUvResponse)
+
+[VerifyTemporaryPinCommand](xref:Yubico.YubiKey.Piv.Commands.VerifyTemporaryPinCommand)
+
+[VerifyTemporaryPinResponse](xref:Yubico.YubiKey.Piv.Commands.VerifyTemporaryPinResponse)
+
+### Input
+
+#### VerifyUvCommand
+
+Two boolean values:
+- request temporary PIN\
+if true, the YubiKey will wait for the user to perform a biometric verification (match an enrolled fingerprint) and, on success, generate a temporary PIN.
+- check only\
+when true, the YubiKey verifies internally that the biometric state is valid. No biometric verification is performed on the YubiKey. 
+
+A client application would typically call the command with `false`, `false` parameters - this will make the YubiKey request the biometric verification from the users.
+
+#### VerifyTemporaryPinCommand
+The temporary PIN is the only parameter.
+
+### Output
+
+#### VerifyUvResponse
+If temporary PIN was requested and the status is Success, the returned value is the temporary PIN.
+In case of failure (for example the fingerprint did not match), the clients should read the `AttemptsRemaining` property which contains number of remaining biometric attempts.
+
+#### VerifyTemporaryPinResponse
+No output. The Status will be Success if the temporary PIN was verified.
+
+### APDU
+
+[Technical APDU Details for VerifyUvCommand](apdu/verify-uv.md)
+
+[Technical APDU Details for VerifyTemporaryPinCommand](apdu/verify-temporary-pin.md)
+___
 ## Authenticate: management key
 
 The Authenticate command can be used to perform several cryptographic operations:
@@ -284,9 +366,9 @@ app knows it is communicating with the appropriate YubiKey. Maybe the app wants
 it will not call on an attacker's YubiKey to perform a sensitive operation. This section
 will refer to this action as <b>YubiKey Authentication</b>.
 
-Hence, the authenticate managment key command can actually perform two different
+Hence, the authenticate management key command can actually perform two different
 operations: "single authentication" (Client Authentication only), or "mutual authentication"
-(Client Authentication and YubiKey Authenticaiton). How you call the API
+(Client Authentication and YubiKey Authentication). How you call the API
 determines which operation will be performed.
 
 The authentication is done using "challenge-response". Note that the word "response" is

Yubico.YubiKey/src/Resources/ExceptionMessages.resx

@@ -279,6 +279,9 @@
   <data name="InvalidSlotsSameSourceAndDestinationSlotsCannotBeTheSame" xml:space="preserve">
     <value>Source and destination slots cannot be the same.</value>
   </data>
+  <data name="InvalidVerifyUvArguments" xml:space="preserve">
+    <value>Cannot request temporary pin when doing check-only verification.</value>
+  </data>
   <data name="InvalidAlgorithm" xml:space="preserve">
     <value>The given algorithm is not valid for the given command.</value>
   </data>
@@ -288,6 +291,9 @@
   <data name="InvalidPinPukLength" xml:space="preserve">
     <value>A PIN or PUK must be 6, 7, or 8 characters long.</value>
   </data>
+  <data name="InvalidTemporaryPinLength" xml:space="preserve">
+    <value>The temporary PIN length is invalid.</value>
+  </data>  
   <data name="InvalidPivPutDataLength" xml:space="preserve">
     <value>The length of input to a Put Data operation, {0}, was invalid, the maximum is {1}.</value>
   </data>
@@ -306,6 +312,9 @@
   <data name="NotSupportedByYubiKeyVersion" xml:space="preserve">
     <value>This operation is not supported by this version of YubiKey.</value>
   </data>
+  <data name="BioMetadataNotSupported" xml:space="preserve">
+    <value>This YubiKey does not support bio metadata.</value>
+  </data>
   <data name="InvalidDataEncoding" xml:space="preserve">
     <value>The data provided does not match the expected encoding.</value>
   </data>

Yubico.YubiKey/src/Resources/ResponseStatusMessages.resx

@@ -258,9 +258,15 @@
   <data name="PivPinPukBlocked" xml:space="preserve">
     <value>Maximum number of retries for user verification (PIN or PUK) exceeded. 0 retries remaining.</value>
   </data>
+  <data name="PivBioUvBlocked" xml:space="preserve">
+    <value>Maximum number of retries for biometric user verification exceeded. 0 retries remaining.</value>
+  </data>
   <data name="PivPinPukFailedWithRetries" xml:space="preserve">
     <value>User verification (PIN or PUK) failed. Retries remaining: {0}.</value>
   </data>
+  <data name="PivBioUVFailedWithRetries" xml:space="preserve">
+    <value>User biometric verification failed. Retries remaining: {0}.</value>
+  </data>  
   <data name="PivSecurityStatusNotSatisfied" xml:space="preserve">
     <value>User verification (PIN, PUK, or Management Key) or presence (touch) requirement not satisfied.</value>
   </data>