Add PIV key management

Nitrokey · Mar 26, 2024 · edbc051 · edbc051
1 parent 581d699
commit edbc051
Show file tree

Hide file tree

Showing 2 changed files with 62 additions and 0 deletions.
diff --git a/nitrokey3/windows/piv/index.rst b/nitrokey3/windows/piv/index.rst
@@ -15,4 +15,6 @@ The *Personal Identity Verfication* (PIV) is based on the NIST special publicati
    access_control.rst
    certificate_management.rst
    factory_reset.rst
+   key_management.rst
+
    guides/index.rst
diff --git a/nitrokey3/windows/piv/key_management.rst b/nitrokey3/windows/piv/key_management.rst
@@ -0,0 +1,60 @@
+Key Management
+==============
+
+Key Slots
+---------
+
+The PIV application can hold certificates for different purposes.
+For each purpose the private key and its corresponding certificate are stored in a key slot.
+
++-------+------------------------+-------------------------------------------------------+
+| Slot  | Application            | Description                                           |
++=======+========================+=======================================================+
+| 82-95 | Retired Key Management | The private keys and certificates in these slots were |
+|       |                        | used for key management applications and are still    |
+|       |                        | there to provide backward compatibility.              |
++-------+------------------------+-------------------------------------------------------+
+| 9a    | Authentication         | The private key and certificate in this slot          |
+|       |                        | are used to authenticate the cardholder.              |
++-------+------------------------+-------------------------------------------------------+
+| 9c    | Signature              | The private key and certificate in this slot          |
+|       |                        | are used to sign emails and files.                    |
++-------+------------------------+-------------------------------------------------------+
+| 9d    | Key Management         | The private key and certificate in this slot          |
+|       |                        | are used to encrypt emails and files.                 |
++-------+------------------------+-------------------------------------------------------+
+| 9e    | Card Authentication    | The private key and certificate in this slot          |
+|       |                        | are used for physical operations, such as building    |
+|       |                        | access or time recording. Support from the respective |
+|       |                        | system is a prerequisite.                             |
++-------+------------------------+-------------------------------------------------------+
+
+Algorithms
+----------
+
+The PIV application uses asymmetric and symmetric algorithms.
+The asymmetric algorithms are used for the user private keys and the symmetric algorithms for the management key.
+
+Supported asymmetric key algorithms:
+
+* RSA 2048
+* nistp256
+
+Supported symmetric key algorithms:
+
+* AES 256
+* 3DES (TDES)
+
+.. warning::
+   It is not recommended to use the 3DES (TDES) algorithm.
+
+Generate Key
+------------
+
+The PIV application can generate a new private key on the Nitrokey.
+
+The command below will create private key in key slot ``9a`` for the user with the subject name ``John Doe`` and subject alternative name ``[email protected]``.
+
+.. code-block::
+
+   nitropy nk3 piv generate-key --key-slot 9a --subject-name "John Doe" --subject-alt-name-upn "[email protected]"