Skip to content

keepassxc troubleshooting link #438

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
May 7, 2025
Merged

keepassxc troubleshooting link #438

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7946796
keepassxc troubleshooting link
alexgithublab Apr 24, 2025
44690c3
herarchy
alexgithublab Apr 29, 2025
15f8e6a
Fix enumerated start value errors (#439)
mmerklinger Apr 29, 2025
72d57d1
Fix enumerated list errors
mmerklinger Apr 30, 2025
e9e0573
code block fix
alexgithublab May 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions source/components/nitrokeys/nitrokey3/troubleshooting.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,11 +151,11 @@ PIV Troubleshooting
Pyscard is not available
------------------------

If pyscard is not available to nitropy, you might get the following error when trying to use the PIV functionality:
If pyscard is not available to nitropy, you might get the following error when trying to use the PIV functionality::

This command requires the pyscard library that is not available on your system. Please consult https://docs.nitrokey.com/nitrokeys/nitrokey3/troubleshooting#pyscard-is-not-available for more information

To fix this error, please install nitropy with the `pcsc` extra dependencies:
To fix this error, please install nitropy with the `pcsc` extra dependencies::

pip install pynitrokey[pcsc]
pipx install pynitrokey[pcsc]
Expand Down
21 changes: 10 additions & 11 deletions source/components/nitrokeys/pro/firmware-update.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,15 +24,15 @@ How to Update
1. Make sure you have the latest `pynitrokey` version installed, please check the `installation instructions <../../software/nitropy/all-platforms/installation.html>`__ for your OS.
2. Download the latest stable `firmware image <https://github.com/Nitrokey/nitrokey-pro-firmware/releases>`__.

.. important::
For production use you should choose the latest stable version (so only versions, that don’t contain i.e. “pre-release” or “RC”).
.. important::
For production use you should choose the latest stable version (so only versions, that don’t contain i.e. “pre-release” or “RC”).

3. To apply the update run:

.. code-block:: bash
.. code-block:: bash

$ nitropy pro enable-update
$ nitropy pro update nitrokey-pro-firmware-<version>.bin
$ nitropy pro enable-update
$ nitropy pro update nitrokey-pro-firmware-<version>.bin


Alternative Update Method
Expand All @@ -42,21 +42,20 @@ Alternatively `dfu-util` can be used for the firmware update:

1. Install dfu-util

* Binaries for Windows are available at: http://dfu-util.sourceforge.net/releases/
* For macOS binaries are available via Homebrew: https://formulae.brew.sh/formula/dfu-util
* Install `dfu-util` via Homebrew
* Binaries for Windows are available `here <http://dfu-util.sourceforge.net/releases/>`__
* For macOS `binaries <https://formulae.brew.sh/formula/dfu-util>`__ are available via Homebrew and can be installed by executing:

.. code-block:: bash
.. code-block:: bash

brew install dfu-util

2. Use Nitrokey App v1.5-RC7 or higher to change the boot mode of the Nitrokey Pro to update mode.

3. Now the following command to apply the update

.. code-block:: bash
.. code-block:: bash

$ dfu-util -D update_binary.bin
$ dfu-util -D update_binary.bin

4. The boot mode can now be changed back again with the Nitrokey App.

Expand Down
77 changes: 54 additions & 23 deletions source/components/software/nk-app2/keepassxc.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,28 +17,25 @@ First Step: Generate a HMAC Secret With the Nitrokey App 2
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 exactly one HMAC secret on a Nitrokey 3.
.. 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 exactly one HMAC secret on a Nitrokey 3.

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, as long as it is compliant.

.. warning::

The database can no longer be unlocked if the Nitrokey 3 is lost or unavailable! Thus, you may want to set up a second Nitrokey 3 with the same HMAC secret as a backup device.

.. important::
.. warning::
The database can no longer be unlocked if the Nitrokey 3 is lost or unavailable! Thus, you may want to set up a second Nitrokey 3 with the same HMAC secret as a backup device.

The secret can **only** be seen before saving. If the KeePassXC database is to be used with another Nitrokey 3, the HMAC secret must be copied which is **only** possible **before saving** the credential.
.. important::
The secret can **only** be seen before saving. If the KeePassXC database is to be used with another Nitrokey 3, the HMAC secret must be copied which is **only** possible **before saving** the credential.

7. Click on ``SAVE`` to save the credential

First Option: Protect an Existing KeePassXC Database With a Nitrokey 3
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
**********************************************************************

1. Open KeePassXC
2. Open the existing KeePassXC database that is to be protected with a Nitrokey 3.
Expand All @@ -51,17 +48,16 @@ First Option: Protect an Existing KeePassXC Database With a Nitrokey 3
Click on ``OK`` to add the Nitrokey 3 to the existing KeePassXC database

.. note::

By default the Nitrokey 3 is used as a second factor in addition to the passphrase. To protect the database by the Nitrokey 3 exclusively, delete the passphrase by clicking the button ``Remove Password``.

.. tip::

If the Nirokey 3 is not recognized, close KeePassXC completely. Then connect the Nitrokey 3 to your computer before restarting KeePassXC.



Second Option: Creating a KeePassXC Database, Protected by Nitrokey 3
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
*********************************************************************

1. Open KeePassXC
2. Select ``Database`` -> ``New Database...`` from the menu bar to create a new KeePassXC database.
3. Fill in the display name and an optional description for your new database and click on ``Continue``
Expand All @@ -78,28 +74,63 @@ Second Option: Creating a KeePassXC Database, Protected by Nitrokey 3
Click on ``Continue`` to complete the creation of the new KeePassXC database.

.. note::

If the passphrase is left empty, the database will be protected by the Nitrokey 3 exclusively. If a passphrase is entered, the database will be protected by the passphrase **and** the Nitrokey 3.

.. tip::

If the Nitrokey 3 is not recognized, close KeePassXC completely. Then connect the Nitrokey 3 to your computer before restarting KeePassXC.

Troubleshooting for Linux
-------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^
If the Nirokey 3 device is not recognised by `KeePassXC <https://keepassxc.org/>`__ on a Linux system:

* Provided that the udev rules have been set as described `here </software/nitropy/linux/udev.html>`__.
* Provided that the ``pcscd service`` are has been started with:

.. code-block:: bash
.. code-block:: bash

sudo systemctl start pcscd.service
sudo systemctl start pcscd.service

* Install the latest version of KeePassXC with flatpak:

.. code-block:: bash
.. code-block:: bash

flatpak install flathub org.keepassxc.KeePassXC
flatpak install flathub org.keepassxc.KeePassXC

* Install ``ccid`` on Arch Linux based systems. See also: `Arch wiki: Nitrokey <https://wiki.archlinux.org/title/Nitrokey>`__.


pcscd: Card Not Found
*********************

**Problem:**
An application using ``pcscd`` does not show the Nitrokey 3.

**Solution:**
First, make sure that ``scdaemon`` is not running (see the previous section)::

$ gpg-connect-agent "SCD KILLSCD" /bye

Now list the smartcards recognized by ``pcscd`` with ``pcsc_scan -r``.
You should see an entry like this one::

$ pcsc_scan -r
Using reader plug'n play mechanism
Scanning present readers..
0: Nitrokey 3 [CCID/ICCD Interface] 00 00

If the Nitrokey 3 shows up, it is recognized correctly by ``pcscd`` and there might be an issue with the application that tries to access it.
If it does not show up, make sure that your ``libccid`` version is up to date.
Support for the Nitrokey 3 was added in ``libccid`` 1.5.0.

Updating The Device Database
****************************

If you cannot update ``libccid`` to a supported version, you have to manually update the device database.
The path of the database depends on your distribution:

- Arch, Debian, Ubuntu: ``/etc/libccid_Info.plist``

Make sure to backup the file before overwriting it.
You can download an `updated device database file <https://github.com/Nitrokey/nitrokey-3-firmware/blob/main/Info.plist>`__ from the ``nitrokey-3-firmware`` repository.
After updating the file, restart ``pcscd`` and run ``pcsc_scan -r`` again.
The Nitrokey 3 should now show up.