Merge pull request #214 from Nitrokey/piv-documentation-improvement

PIV documentation improvement

nitrokey3/linux/index.rst

@@ -1,4 +1,13 @@
 Nitrokey 3 With Linux
 ===========================
 
+.. contents:: :local:
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+   :hidden:
+
+   *
+
 .. include:: ../shared/main.rst

nitrokey3/mac/index.rst

@@ -1,4 +1,13 @@
 Nitrokey 3 With macOS
 =====================
 
+.. contents:: :local:
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+   :hidden:
+
+   *
+
 .. include:: ../shared/main.rst

nitrokey3/shared/main.rst

@@ -1,12 +1,3 @@
-.. contents:: :local:
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-   :hidden:
-
-   *
-
 The Nitrokey 3 supports two-factor authentication (2FA) and
 passwordless authentication:
 

nitrokey3/windows/index.rst

@@ -1,4 +1,14 @@
 Nitrokey 3 With Windows
 ===========================
 
+.. contents:: :local:
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+   :hidden:
+
+   *
+   piv/index.rst
+
 .. include:: ../shared/main.rst

nitrokey3/windows/piv/access_control.rst

@@ -0,0 +1,87 @@
+Access Control
+==============
+
+The following access matrix shows what authentication a certain operation requires.
+
++-------------------+-----+-----+-----+-------------------------------------------------+
+| Operation         | PIN | PUK | MGM | Remarks                                         |
++===================+=====+=====+=====+=================================================+
+| Change PIN        |  x  |     |     |                                                 |
++-------------------+-----+-----+-----+-------------------------------------------------+
+| Change PUK        |     |  x  |     |                                                 |
++-------------------+-----+-----+-----+-------------------------------------------------+
+| Change MGM        |     |     |  x  |                                                 |
++-------------------+-----+-----+-----+-------------------------------------------------+
+| Unblock PIN       |     |  x  |     |                                                 |
++-------------------+-----+-----+-----+-------------------------------------------------+
+| Generate key      |  x  |     |  x  |                                                 |
++-------------------+-----+-----+-----+-------------------------------------------------+
+| Read certificate  |     |     |     | This operatain does not require authentication. |
++-------------------+-----+-----+-----+-------------------------------------------------+
+| Write certificate |  x  |     |  x  |                                                 |
++-------------------+-----+-----+-----+-------------------------------------------------+
+
+
+Personal Identification Number (PIN)
+------------------------------------
+
+The *PIN* is used for key operations, such as signing and authentication.
+The factory default for the *PIN* is ``123456``.
+
+.. note::
+   The *PIN* must have maximal length of 8 characters.
+   It can contain alphanumeric characters, including special characters such as punctations.
+
+.. warning::
+   The *PIN* is subject to the restriction of a retry counter.
+   Please refer to the chapter `Retry Counter <access_control.html#retry-counter>`__ to learn more.
+
+1. Connect the Nitrokey 3 with your computer.
+2. On the terminal enter ``nitropy nk3 piv change-pin``.
+
+
+Personal Unblocking Key (PUK)
+-----------------------------
+
+The *PUK* is used for management operations, such as unblocking the PIN.
+The factory default for the *PUK* is ``123456``.
+
+.. note::
+   The *PUK* must have a maximal length of 8 characters.
+   It can contain alphanumeric characters, including special characters such as punctations.
+
+.. warning::
+   The *PUK* is subject to the restriction of a retry counter.
+   Please refer to the chapter `Retry Counter <access_control.html#retry-counter>`__ to learn more.
+
+1. Connect the Nitrokey 3 with your computer.
+2. On the terminal enter ``nitropy nk3 piv change-puk``.
+
+
+Retry Counter
+-------------
+
+The retry counter is used for the *PIN* and *PUK*.
+The counter decrements for every failed login attempt.
+A retry counter of zero means that there are no attempts left.
+
+The *PIN* has a retry counter of 3 attempts.
+If these attempts are used up, the *PIN* must be unlocked with the *PUK*.
+
+To unblock the *PIN*, use the command ``nitropy nk3 piv reset-retry-counter``.
+This command requires the *PUK*.
+
+The *PUK* has a retry counter of 3 attempts.
+If these attempts are used up, the PIV Card can not be used anymore and must be reset to factory defaults.
+Please refer to the chapter `Factory Reset <factory_reset.html>`__ to learn more.
+
+
+Management Key (MGM)
+--------------------
+
+The management key is used for management operations.
+
+Before you can perform management operations you must authenticate with the management key.
+The authentication is done with ``nitropy nk3 piv admin-auth``.
+
+The management key can be changed with ``nitropy nk3 piv change-admin-key``.

nitrokey3/windows/piv/certificate_management.rst

@@ -0,0 +1,27 @@
+Certificate Management
+======================
+
+Every private key has a certificate associated. The certificates can be read and written.
+The size of a certificate is limited by the transport layer and about 6kB.
+
+
+Read Certificate
+----------------
+
+Certificates can be read from the Nitrokey per key slot.
+
+The certificate can be retrieved as follows.
+
+.. code-block::
+
+    nitropy nk3 piv read-certificate --key-slot <key-slot>``
+
+
+Write Certificate
+-----------------
+
+Certificates can be written to the Nitrokey per key slot.
+
+.. code-block::
+
+    nitropy nk3 piv write-certificate --key-slot <key-slot>

nitrokey3/windows/piv/factory_reset.rst

@@ -0,0 +1,14 @@
+Factory Reset
+=============
+
+The PIV application can be reset to factory defaults.
+It can only be reset if the PIN and PUK are blocked.
+
+.. warning::
+   Performing a factory reset of the PIV application will delete all private keys and certificates.
+
+The reset to factory defaults can be performed as follows.
+
+.. code-block::
+
+    nitropy nk3 piv factory-reset