Add design document. Move all to docs.

Nitrokey · Aug 12, 2023 · 48a5d25 · 48a5d25
1 parent 518e8d6
commit 48a5d25
Show file tree

Hide file tree

Showing 3 changed files with 21 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -99,7 +99,7 @@ e.g. due to being taken by other services, or requiring Administrator
 privileges). A CTAPHID vendor command number was selected to use (`0x70`), thus allowing for a compatible extension of
 any FIDO compliant device.
 
-See [CTAPHID](ctaphid.md) for the further documentation regarding the NLnet funded CTAPHID extension.
+See [CTAPHID](docs/ctaphid.md) for the further documentation regarding the NLnet funded CTAPHID extension.
 
 ### Further work
 
@@ -119,6 +119,8 @@ Tasks and features still discussed to be done:
 
 ### Development
 
+See [design](docs/design.md) document to see decisions taken to make the solution cohesive.
+
 Use `dangerous_disable_encryption` Rust flag to disable data encryption for the debug purposes. E.g.:
 
 ```text

diff --git a/ctaphid.md → docs/ctaphid.md b/ctaphid.md → docs/ctaphid.md
@@ -167,8 +167,9 @@ None
 
 ## Tests
 
-The tests for communication and responses correctness according to the RFC test vectors are provided in `test_otp.py`
-file.
+The tests for communication and responses correctness according to the RFC test vectors are provided in `test_secrets_app.py`
+file, located in the pynitrokey repository:
+- https://github.com/Nitrokey/pynitrokey/blob/master/pynitrokey/test_secrets_app.py
 
 These can be run against a USB/IP device simulation of Nitrokey 3.
 

diff --git a/docs/design.md b/docs/design.md
@@ -0,0 +1,15 @@
+# Design
+
+The following design choices have been implemented to strike a balance between the secure utilization and
+user-friendliness of the Secrets App project. These decisions originated from the YKOATH protocol and were compared with
+alternative offline solutions. Throughout this process, the aim was to ensure a basic level of safeguarding against
+malware threats by incorporating physical user presence confirmation for critical operations.
+
+[YKOATH]: https://developers.yubico.com/OATH/YKOATH_Protocol.html
+
+|                        | 1\. Daily use                                               | 2\. Registration / modification                                                 | 3\. Factory Reset confirmation                                                                                           | 4\. PINs / passphrases | 5\. PIN change guard         | 6\. Attack vector protection | 7\. Token validation period                     | Comments                                                                                                                                                                                                                          |
+|------------------------|-------------------------------------------------------------|---------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|------------------------|------------------------------|------------------------------|-------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Secrets App v0.10+     | Touch button if set, and/or<br>PIN if set on the Credential | Touch button always, before processing (to prevent PIN attempt counter use up). | Touch button                                                                                                             | Single PIN only        | Current PIN and Touch button | Local / Malware              | Each request, where PIN is needed (per request) | Do not require PIN for user data, but offer such possibility. Keep all encrypted. PIN-encrypted Credentials are not listed until PIN is provided. Touch button should always protect PIN use to prevent local malware DOS attack. |
+| Secrets App Next (TBD) | (no changes)                                                | (no changes)                                                                    | \- Touch button<br>\- Within 10 seconds of power cycle only<br>\- Significant UX event – LED animation red/blue blinking | (no changes)           | (no changes)                 | (no changes)                 | (no changes)                                    | (no changes)                                                                                                                                                                                                                      |
+
+