Documentation updates for release 1.11. #126

equijano21 · 2024-07-10T17:28:50Z

Description

Documentation updates for release 1.11.

Type of change

API doc (.cs) and user's manual doc (.md and .yml) updates.

How has this been tested?

Built docs locally.

github-actions · 2024-07-10T17:31:23Z

Test Results: Windows

2 files 2 suites 4s ⏱️
3 700 tests 3 700 ✅ 0 💤 0 ❌
3 702 runs 3 702 ✅ 0 💤 0 ❌

Results for commit b47bcff.

♻️ This comment has been updated with latest results.

github-actions · 2024-07-10T17:31:31Z

Test Results: Ubuntu

2 files 2 suites 9s ⏱️
3 692 tests 3 692 ✅ 0 💤 0 ❌
3 694 runs 3 694 ✅ 0 💤 0 ❌

Results for commit b47bcff.

♻️ This comment has been updated with latest results.

github-actions · 2024-07-10T17:31:38Z

Test Results: MacOS

2 files 2 suites 3s ⏱️
3 692 tests 3 692 ✅ 0 💤 0 ❌
3 694 runs 3 694 ✅ 0 💤 0 ❌

Results for commit b47bcff.

♻️ This comment has been updated with latest results.

equijano21 · 2024-07-10T17:47:50Z

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

Added some links and info, reworded things, and moved a few bullet points around.

equijano21 · 2024-07-10T17:49:38Z

Yubico.YubiKey/docs/users-manual/toc.yml

Some of the new APDU articles hadn't made it into the TOC yet.

equijano21 · 2024-07-10T17:50:12Z

Yubico.YubiKey/docs/users-manual/sdk-programming-guide/pin-complexity-policy.md

Reworked this article to improve clarity and flow. Added lots of relevant links.

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

equijano21 · 2024-07-10T17:54:41Z

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

@@ -117,10 +120,12 @@ namespace Yubico.YubiKey.Piv
    ///             management key (hex): 01 02 03 04 05 06 07 08
    ///                                   01 02 03 04 05 06 07 08
    ///                                   01 02 03 04 05 06 07 08
-    ///             
+    ///         </code>


Had to add these to fix a weird problem where the rest of the remarks section (lines 127-145) was formatted as a code box instead of a regular paragraph.

equijano21 · 2024-07-10T17:56:50Z

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


-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.
+The YubiKey keeps track of failed biometric matches and will block biometric authentication if there are more than three such failures. In that case, the client should use the [PIV PIN verification](#verify) as soon as possible. The number of remaining biometric verification attempts is returned in the command response's `AttemptsRemaining` property. The value is present only after a failed match.


Assuming this was referring to the PIV PIN, but please correct if wrong.

That is correct 👍🏻

as soon as possible

is there a time aspect to this?

If not, perhaps it should read:

In that case, the client must use the PIV PIN verification in order to unblock the Yubikey and proceed operations.

Yubico.YubiKey/docs/users-manual/sdk-programming-guide/pin-complexity-policy.md

AdamVe · 2024-07-11T06:42:20Z

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

- none  - for checking the biometric state
- 02 00 - if temporary PIN has been requested
- 03 00 - if biometric verification has been requested
+- none  - the biometric state has been checked


I think we should change this a little bit.
If the instruction is called without any data, it queries the YubiKey for the verification state of biometrics. In the case of unverified state, the YubiKey will respond with 63 CX, in the case of a verified state 90 00.
When the state is unverified, the biometrics should not be used, but the PIN verification should be used.

I see. But isn't this addressed below in the document on line 55 and onwards?

I added the info about PIV PIN verification and a link to the relevant APDU page to line 59: 0d76f0b. Let me know if this is sufficient.

I reviewed the implementation documentation again and the addition in 0d76f0b could be improved, mentioning that: If all the biometric match retries have been used up, then a 0x6983 error is returned instead. That error is called AuthenticationMethodBlocked.

For the line 25 in this review (where I marked this comment), the line is changed from "for checking the biometric state" to "the biometric state has been checked". I don't think this is accurate as when we call the instruction nothing has been checked yet - we are instructing the YubiKey to response to us what the current verification state of biometrics is.

Thanks for catching that, Adam! The tense of the other two lines threw me.

Changes made here: ab28b45. Let me know if this covers it.

This looks very good now :) Thank you.

AdamVe

Thank you for the changes, it looks good to me. Before merging, the verify-uv file for the "none" case could be updated.

DennisDyallo

Great work @equijano21 . I think it looks very good. It's like it actually makes sense to the end user now somehow... :)

DennisDyallo · 2024-07-11T10:52:35Z

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

@@ -22,9 +22,9 @@ CLA | INS | P1 | P2 | Lc | Data | Le
 00 | 20 | 00 | 96 | *variable* | *variable* | (absent)


Suggested change

00 | 20 | 00 | 96 | *variable* | *variable* | (absent)

| CLA | INS | P1 | P2 | Lc | Data | Le |

|:---:|:---:|:--:|:--:|:----------:|:----------:|:--------:|

| 00 | 20 | 00 | 96 | *variable* | *variable* | (absent) |

The table seems to be missing the |s and correct number of padding columns making it not a fully valid markdown table. I have pasted a suggestion which should work.

Weirdly enough, it doesn't seem to matter whether those extra "|" are there or not--the table still looks and behaves the same (when changing the window size). All of the tables in all of the PIV APDU files are formatted this way, but if you want me to change it, I can do it for everything. Just let me know.

Ok, no need. I guess that most markdown processors handle the invalid format still.
I'm in the process of doing in in another commit where I address all of the incorrectly formatted tables in all the other markdown files.

DennisDyallo · 2024-07-11T11:24:20Z

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

- none  - for checking the biometric state
- 02 00 - if temporary PIN has been requested
- 03 00 - if biometric verification has been requested
+- none  - the biometric state has been checked


I see. But isn't this addressed below in the document on line 55 and onwards?

DennisDyallo · 2024-07-11T11:29:20Z

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


-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.
+The YubiKey keeps track of failed biometric matches and will block biometric authentication if there are more than three such failures. In that case, the client should use the [PIV PIN verification](#verify) as soon as possible. The number of remaining biometric verification attempts is returned in the command response's `AttemptsRemaining` property. The value is present only after a failed match.


as soon as possible

is there a time aspect to this?

If not, perhaps it should read:

In that case, the client must use the PIV PIN verification in order to unblock the Yubikey and proceed operations.

Yubico.YubiKey/docs/users-manual/sdk-programming-guide/pin-complexity-policy.md

equijano21 · 2024-07-11T17:12:40Z

Great work @equijano21 . I think it looks very good. It's like it actually makes sense to the end user now somehow... :)

Thanks, Dennis! Really appreciate the feedback :)

AdamVe

LGTM!

DennisDyallo

Improving sensitive-data.md to address #70

github-actions · 2024-07-29T10:58:53Z

Package	Line Rate	Branch Rate	Complexity	Health
Yubico.Core	42%	31%	4257	➖
Yubico.YubiKey	50%	47%	19089	➖
Summary	49% (31993 / 65943)	44% (8185 / 18519)	23346	➖

Minimum allowed line rate is 40%

equijano21 added 5 commits July 3, 2024 12:31

updates to piv bio docs

cf47560

updates to 1.11 release notes

982ab03

edits to pin complexity article

0ea5cec

additional updates, fixed formatting issues

f177ec5

minor punctuation changes

001bcfe

equijano21 marked this pull request as draft July 10, 2024 17:29

equijano21 commented Jul 10, 2024

View reviewed changes

Yubico.YubiKey/src/Yubico/YubiKey/Piv/Commands/VerifyUvResponse.cs Show resolved Hide resolved

equijano21 commented Jul 10, 2024

View reviewed changes

equijano21 marked this pull request as ready for review July 10, 2024 17:57

equijano21 requested review from DennisDyallo and AdamVe July 10, 2024 17:58

equijano21 added the documentation Improvements or additions to documentation label Jul 10, 2024

equijano21 changed the title ~~Docs/1.11 updates~~ Documentation updates for release 1.11. Jul 10, 2024

equijano21 commented Jul 10, 2024

View reviewed changes

Yubico.YubiKey/docs/users-manual/sdk-programming-guide/pin-complexity-policy.md Show resolved Hide resolved

AdamVe reviewed Jul 11, 2024

View reviewed changes

DennisDyallo approved these changes Jul 11, 2024

View reviewed changes

equijano21 added 2 commits July 11, 2024 10:47

updates to verify-uv.md as requested by reviewers

0d76f0b

added info about Bio MPE device reset

3b234d5

equijano21 mentioned this pull request Jul 11, 2024

Add device reset command #110

Merged

12 tasks

DennisDyallo mentioned this pull request Jul 12, 2024

Formatting markdown files #127

Merged

updated verify-uv tense, error info

ab28b45

updates to device reset docs

2624161

AdamVe approved these changes Jul 15, 2024

View reviewed changes

DennisDyallo added 2 commits July 29, 2024 10:56

Adding section on bio policies

b47bcff

Improved sensitive-data.md

f232f78

DennisDyallo approved these changes Jul 29, 2024

View reviewed changes

DennisDyallo merged commit 5b4949a into develop Jul 29, 2024
6 checks passed

DennisDyallo deleted the docs/1.11-updates branch July 29, 2024 10:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation updates for release 1.11. #126

Documentation updates for release 1.11. #126

equijano21 commented Jul 10, 2024

github-actions bot commented Jul 10, 2024 •

edited

Loading

github-actions bot commented Jul 10, 2024 •

edited

Loading

github-actions bot commented Jul 10, 2024 •

edited

Loading

equijano21 Jul 10, 2024

equijano21 Jul 10, 2024

equijano21 Jul 10, 2024

equijano21 Jul 10, 2024

equijano21 Jul 10, 2024

AdamVe Jul 11, 2024

DennisDyallo Jul 11, 2024

AdamVe Jul 11, 2024

DennisDyallo Jul 11, 2024

equijano21 Jul 11, 2024

AdamVe Jul 12, 2024

equijano21 Jul 12, 2024

AdamVe Jul 15, 2024

AdamVe left a comment

DennisDyallo left a comment

DennisDyallo Jul 11, 2024

DennisDyallo Jul 11, 2024

equijano21 Jul 11, 2024

DennisDyallo Jul 12, 2024

DennisDyallo Jul 11, 2024

DennisDyallo Jul 11, 2024

equijano21 commented Jul 11, 2024

AdamVe left a comment

DennisDyallo left a comment •

edited

Loading

github-actions bot commented Jul 29, 2024


		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.
		The YubiKey keeps track of failed biometric matches and will block biometric authentication if there are more than three such failures. In that case, the client should use the [PIV PIN verification](#verify) as soon as possible. The number of remaining biometric verification attempts is returned in the command response's `AttemptsRemaining` property. The value is present only after a failed match.

		@@ -22,9 +22,9 @@ CLA \| INS \| P1 \| P2 \| Lc \| Data \| Le
		00 \| 20 \| 00 \| 96 \| variable \| variable \| (absent)

-| 20 | 00 | 96 | *variable* | *variable* | (absent)
+| CLA | INS | P1 | P2 |     Lc     |    Data    |    Le    |
+|:---:|:---:|:--:|:--:|:----------:|:----------:|:--------:|
+| 00  | 20  | 00 | 96 | *variable* | *variable* | (absent) |

Documentation updates for release 1.11. #126

Documentation updates for release 1.11. #126

Conversation

equijano21 commented Jul 10, 2024

Description

Type of change

How has this been tested?

github-actions bot commented Jul 10, 2024 • edited Loading

Test Results: Windows

github-actions bot commented Jul 10, 2024 • edited Loading

Test Results: Ubuntu

github-actions bot commented Jul 10, 2024 • edited Loading

Test Results: MacOS

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AdamVe left a comment

Choose a reason for hiding this comment

DennisDyallo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

equijano21 commented Jul 11, 2024

AdamVe left a comment

Choose a reason for hiding this comment

DennisDyallo left a comment • edited Loading

Choose a reason for hiding this comment

github-actions bot commented Jul 29, 2024

github-actions bot commented Jul 10, 2024 •

edited

Loading

github-actions bot commented Jul 10, 2024 •

edited

Loading

github-actions bot commented Jul 10, 2024 •

edited

Loading

DennisDyallo left a comment •

edited

Loading