From e38b70e8a08aaa45304a06802a3a6467a223ca22 Mon Sep 17 00:00:00 2001
From: jj-so <janos@nitrokey.com>
Date: Tue, 2 Apr 2024 12:51:53 +0200
Subject: [PATCH] KeePassXC

---
 software/nk-app2/keepassxc.rst | 103 +++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 software/nk-app2/keepassxc.rst

diff --git a/software/nk-app2/keepassxc.rst b/software/nk-app2/keepassxc.rst
new file mode 100644
index 0000000000..9306d1286a
--- /dev/null
+++ b/software/nk-app2/keepassxc.rst
@@ -0,0 +1,103 @@
+KeePassXC
+=========
+.. _keepassxc:
+
+KeePassXC with Nitrokey3:
+
+To use KeePassXC with the Nitokey, the Nitrokey3 must have a 
+add a challenge-response secret
+
+1. Generate a Hmac secret with the Nitrokey2App
+2. Creating a KeePassXC database that is connected to a Nitrokey3
+3. Connection to an existing KeePassXC database that is connected to a Nitrokey3
+4. Troubleshooting
+
+
+1. Generate a Hmac secret with the Nitrokey2App
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Open Nitrokey2App
+2. Select the Nitrokey3
+3. Select the ``PASSWORDS`` Tab
+4. Click on ``ADD`` to create a new credential
+5. Select HMAC from the algorithm drop-down menu
+
+.. note::
+    - The credential is automatically named in HmacSlot2.
+    - No extra attributes can be saved for the Hmac credential.
+    - The Hmac secret must be *exactly 20 bytes* long and in *Base32* format. That is exactly 32 characters.
+    - It is possible to save 1 Hmac secret on a Nitrokey3
+
+6. To generate a secret, there is a button in the field on the right-hand
+   - It is also possible to enter your own secret that conforms
+
+.. note::
+    - The secret can **only** be seen before saving.
+    - If the KeePassXC database is to be used with another Nitrokey3, 
+      the challenge-response secret must be copied; 
+      this is only possible **before saving** the credential. 
+
+7. Click on ``SAVE`` to save the credential
+
+
+2. Creating a KeePassXC database that is connected to a Nitrokey3
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. note::
+    The connection between a KeePassXC database and the Nirokey3
+    is supported since **KeePassXC version 2.7.6** 
+
+1. Open KeePassXC 
+2. Select ``Database``|
+                      -> ``New Database...`` from the menu bar.
+   Or use the keyboard shortcut ``Ctrl+Shift+N`` to create a new KeePassXC database
+3. Fill in the display name and an Optional description for your new database and click on ``Continue``
+4. Further database encryption settings can now be configured here or the default settings can be retained.
+   The settings can also be changed later in the database settings.
+   For more information look here: https://keepassxc.org/docs/
+   Click on ``Continue`` to confirm the settings.
+5. **Database Credential**
+   Here you can now enter a password to unlock the database. 
+
+.. note::
+    - If the database is only to be unlocked with the help of a Nitrokey3, the password can simply be left blank.
+    - If a password is also entered, the Nitrokey3 is the second factor of the two-factor authorization for unlocking the KeePassXC database. 
+
+   To connect the Nitrokey3 on which the Hmac secret was generated to the new KeePassXC database,
+   click on ``Add additional protection...``
+6. Scroll down to ``Challenge-Response``
+   -> Click on ``Add Challenge-Response``
+7. Now if the Nitrokey3 is plugged in and a Hmac was generated before, Nitrokey3 should be displayed in the field.
+   Click on ``Continue`` to complete the creation of the new KeePassXC database.
+
+.. note::
+    If the Nirokey3 is not recognized, close KeePassXC again completely.
+    Before restarting KeePassXC, connect the Nitrokey3 to the PC
+
+3. Connection to an existing KeePassXC database that is connected to a Nitrokey3
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Open KeePassXC 
+2. Open the existing KeePassXC database that is connected to a Nitrokey3
+3. Select ``Database``|
+                      -> ``Database Security...`` from the menu bar.
+4. Select ``Security`` on the left side
+5. Click on the ``Add additional protection...`` button in the ``Database Credentials`` tab
+6. Scroll down to ``Challenge-Response``
+   -> Click on ``Add Challenge-Response``
+7. Now if the Nitrokey3 is plugged in and a Hmac was generated before, Nitrokey3 should be displayed in the field.
+   Click on ``OK`` to to Add the Nirokey3 to the existing KeePassXC database.
+
+.. note::
+    If the Nirokey3 is not recognized, close KeePassXC again completely.
+    Before restarting KeePassXC, connect the Nitrokey3 to the PC
+
+4. Troubleshooting
+^^^^^^^^^^^^^^^^^^
+
+On Linux
+--------
+
+Close all KeePassXC instances, then run the following command.
+
+``sudo systemctl start pcscd.service``
+