document Nitrokey Passkey (#404)

---------

Co-authored-by: alexgithublab <gentil@et.esiea.fr>
Co-authored-by: jans23 <jans23@users.noreply.github.com>
Co-authored-by: Markus Merklinger <markus@nitrokey.com>

Author: 4 people

source/components/nitrokeys/passkey/faq.rst

@@ -0,0 +1,39 @@
+Nitrokey Passkey FAQ
+====================
+
+**Q:** Which Operating Systems are supported?
+   Windows, Linux, macOS and BSD. Also FIDO2 is supported on Android and iOS.
+
+**Q:** What can I use the Nitrokey Passkey for?
+   Second or first factor authentication for services which support Webauthn/Passkey/FIDO2/FIDO U2F. 
+   See the `overview <https://www.nitrokey.com/products/nitrokeys>`_  of supported use cases.
+
+**Q:** How can I check if my Nitrokey Passkey is working?
+   On `WebAuthn.io`_ you can check various high-level functionalities, while
+   `webautn.bin.coffee`_ provides good developer level details (technical)
+   details.
+   You can also test your Nitrokey with `nitropy`_.
+
+**Q:** What happens if I lose my Nitrokey Passkey device?
+   When securing accounts using FIDO2 (two-factor authentication and
+   passwordless login), you should configure another factor in your account as
+   a backup. Depending on the service this backup factor can be a phone number,
+   an app or even a second Nitrokey Passkey. If you lose a Nitrokey Passkey, you
+   can still log in with the second Nitrokey Passkey (or with another second
+   factor).
+
+**Q:** How large is the storage capacity?
+   The Nitrokey Passkey doesn't contain storage capability for ordinary data (it can
+   only store cryptographic keys). It can hold over 100 passkeys resp. FIDO2 keys.
+
+**Q:** How to use Nitrokey Passkey with Azure Entra ID (Active Directory)?
+   After `disabling Enforce Attestation`_ Nitrokey Passkey is supported by Azure Entra ID out of the box.
+
+**Q:** Why does the Nitrokey Passkey not show up in GnuPG?
+  The Nitrokey Passkey has no support for OpenPGP. 
+
+**Q:** Why does the Nitrokey Passkey not show up in Nitrokey App?
+  The Nitrokey Passkey is not supported by the Nitrokey App 1 and 2.
+
+.. include:: ../../shared-faqs/hyperlinks.rst.inc 
+.. _nitropy: ../../software/nitropy/index.html

source/components/nitrokeys/passkey/getting-started.rst

@@ -0,0 +1,64 @@
+Getting Started
+===============
+
+Passkeys are a modern way to log into websites and apps without the need for traditional passwords, making it easier and safer for everyone. 
+Here’s a simple breakdown of what passkeys are, how they work, and how to use the Nitrokey Passkey.
+ 
+How do Passkeys Work?
+--------------------- 
+
+Passkeys are a modern form of authentication that replaces passwords. 
+First you register your Nitrokey Passkey to a website. This way a secret is stored on your Nitrokey Passkey.
+The magic happens when you log in:
+
+When you want to access the service, the website will send a challenge to your device.
+If you haven't already done so, you plug in your Nitrokey and authenticate it (often via a button press or PIN). 
+Your device uses the private key to respond securely to a challenge from the website, confirming your identity without sending your information across.
+
+First Steps
+-----------
+The Nitrokey Passkey supports two-factor authentication (2FA) and
+passwordless authentication:
+
+-  With **passwordless authentication**, entering a password is replaced
+   by logging in with the Nitrokey Passkey and a PIN.
+
+-  With **two-factor authentication** (2FA), the Nitrokey Passkey is
+   checked in addition to the password.
+
+The Nitrokey Passkey can be used with any current browser.
+
+.. important::
+
+   The Nitrokey App can not be used for the Nitrokey Passkey.
+
+Passwordless Authentication
+---------------------------
+
+1. Open a web page that supports FIDO2 (for example
+   `Google <https://myaccount.google.com/>`__).
+2. Log in to the website and go to “Passkeys and security keys” in the security
+   settings of your account.
+3. Click on Create passkey.
+4. Click on Use a different device.
+5. Follow the prompts to set a PIN for your Nitrokey Passkey.
+6. Touch the button of your Nitrokey Passkey when prompted.
+7. Once you have successfully configured the device, you will need to
+   activate your Nitrokey Passkey this way each time you log in, after
+   entering your PIN.
+
+Two-Factor Authentication (2FA)
+-------------------------------
+
+1. Open one of the `websites that support FIDO
+   U2F <https://www.dongleauth.com/>`__.
+2. Log in to the website and enable two-factor authentication in your
+   account settings. (In most cases you will find a link to the
+   documentation of the supported web service at
+   `dongleauth.com <https://www.dongleauth.com/>`__)
+3. Register your Nitrokey Passkey in the account settings by touching the
+   button to activate the Nitrokey Passkey. After you have successfully
+   configured the device, you must activate the Nitrokey Passkey this way
+   each time you log in.
+
+You are now ready to go.

source/components/nitrokeys/passkey/images/Passkey.webp

@@ -1,7 +1,13 @@
 Nitrokey Passkey
 ================
 
-.. contents:: :local:
+Introduction
+------------
+
+The Nitrokey Passkey is a secure authentication device designed to enhance two-factor authentication (2FA) and passwordless login using the FIDO2/WebAuthn standard. 
+It provides a convenient way to protect digital identities by securely storing cryptographic keys within the hardware, ensuring sensitive information never leaves the device. 
+Compatible with various platforms, including Windows, macOS, Linux, and mobile devices, the Nitrokey Passkey supports popular services such as Google and Microsoft without requiring proprietary software. 
+With a focus on security and user privacy, the Nitrokey Passkey is an excellent choice for individuals and organizations looking to improve their cybersecurity.
 
 The Nitrokey Passkey is the successor to the Nitrokey FIDO2. It is build on top of the technologies
 and framework used within the Nitrokey 3. Find the latest `release notes`_ on GitHub.
@@ -11,3 +17,22 @@ Please see the :doc:`FIDO2 <../fido2/index>` pages for more FIDO2 related docume
 Currently there is only one firmware version, so no firmware update is necessary.
 
 .. _release notes: https://github.com/Nitrokey/nitrokey-passkey-firmware/releases
+
+.. contents:: :local:
+
+First check the:
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   Getting Started <getting-started>
+   Frequently Asked Questions <faq>
+   Troubleshooting <troubleshooting>
+   LED and Touch Button <led>
+   Management <management>
+
+or check out the features:
+
+* `FIDO2 <../features/fido2/index.html>`_
+* `U2F <../features/u2f/index.html>`_

source/components/nitrokeys/passkey/images/chromium_key_managment.png

@@ -0,0 +1,23 @@
+LED and Touch Button
+====================
+
+The first FIDO operation is automatically accepted within two seconds
+after connecting Nitrokey Passkey. In this case touching the touch button
+is not required.
+
+Multiple operations can be accepted by a single touch. For this, keep
+the touch button touched for up to 10 seconds.
+
++------------------+-----------------------------+
+| LED Color        | Event                       |
++==================+=============================+
+| White (blinking) | waiting for touch event     |
++------------------+-----------------------------+
+| Teal (constant)  | processing                  |
++------------------+-----------------------------+
+| Red (Constant)   | Crash                       |
++------------------+-----------------------------+
+
+.. figure:: images/Passkey.webp
+   :alt: img1
+

source/components/nitrokeys/passkey/images/manage_options_w10.PNG

@@ -0,0 +1,62 @@
+Manage Your Nitrokey Passkey
+============================
+
+Browser
+-------
+
+.. note::
+
+    This works with all Chromium based web browsers and with all OSes.
+
+In your Chromium based browser settings, go to "Privacy and security" → "Security" and "Manage security keys".
+
+From this point you will have access to theses management options:
+
+.. figure:: images/chromium_key_managment.png
+   :alt: img1
+
+.. note::
+
+    Some option may be shown but will not work with your Nitrokey eg. Fingerprints.
+
+Windows
+-------
+
+In order to manage your Nitrokey Passkey in Windows, go to "Settings" → "Accounts" → "Sign-in options" → "Security Key" and click "Manage".
+
+.. figure:: images/w10_passkey_manage.png
+   :alt: img2
+
+After touching your Nitrokey you will have two management options:
+
+.. figure:: images/manage_options_w10.PNG
+   :alt: img3
+
+nitropy
+-------
+
+You can use the command line tool `nitropy <../../software/nitropy/index.html>`__ to manage the Nitrokey Passkey:
+
+.. code-block:: bash
+
+   ~ nitropy nkpk
+
+   Command line tool to interact with Nitrokey devices 0.7.4
+   Usage: nitropy nkpk [OPTIONS] COMMAND [ARGS]...
+
+    Interact with Nitrokey Passkey devices, see subcommands.
+
+    Options:
+     -p, --path TEXT  The path of the Nitrokey 3 device
+     -h, --help       Show this message and exit.
+
+    Commands:
+    fetch-update     Fetches a firmware update and stores it at the given...
+    list             List all devices.
+    reboot           Reboot the key.
+    rng              Generate random data on the device.
+    status           Query the device status.
+    test             Run some tests on all connected devices.
+    validate-update  Validates the given firmware image and prints the...
+    version          Query the firmware version of the device.
+

source/components/nitrokeys/passkey/images/w10_passkey_manage.png

@@ -0,0 +1,47 @@
+
+Troubleshooting
+===============
+
+General
+-------
+
+* On `WebAuthn.io`_ you can check various high-level functionalities, while `webautn.bin.coffee`_ provides good developer level details (technical) details.
+
+* Check if the LED is working as `expected`_.
+
+* You can test the Nitrokey Passkey using `nitropy`_ with  ``nitropy nkpk test``.
+
+Windows
+-------
+
+To check whether the Nitrokey Passkey is correctly recognized, open the Device Manager and check for the Nitrokey Passkey appearing as a USB device.
+
+macOS
+-----
+
+To check whether the Nitrokey Passkey is correctly recognized, open the System Report and check for the Nitrokey Passkey appearing as a USB device.
+Otherwise you can use the commandline with the following command to check if your system recognizes the Nitrokey Passkey. 
+
+.. code-block:: bash
+
+   system_profiler SPUSBDataType | grep Nitrokey
+
+Linux
+-----
+
+To check whether the Nitrokey Passkey is correctly recognized, check if it is shown with `lsusb`.
+
+If the Nitrokey is not detected, proceed the following:
+
+1. Copy this file
+   `41-nitrokey.rules <https://www.nitrokey.com/sites/default/files/41-nitrokey.rules>`__
+   to ``/etc/udev/rules.d/``. In very rare cases, the system will need
+   the `older
+   version <https://raw.githubusercontent.com/Nitrokey/libnitrokey/master/data/41-nitrokey_old.rules>`__
+   of this file.
+2. Restart udev via ``sudo service udev restart`` or ``udevadm control --reload-rules && udevadm trigger`` if you are using Fedora.
+
+
+.. include:: ../../shared-faqs/hyperlinks.rst.inc 
+.. _nitropy: ../../software/nitropy/index.html
+.. _expected: ./led.html