PIV doc improvements (#424)

mmerklinger · web-flow · commit bf65911a12ca · 2025-05-21T14:56:03.000+02:00
* Simplify certificate listing with PowerShell

* Update set PIN for PIV

* Correct commands in PIV setup guide

* Add --experimental option to piv subcommands in PIV guide

* Add instructions about certificate mapping

* Add --experimental flag on all piv commands

* Use same terminology to refer to PIV smart card

* Correct key slot option

* Fix typo

* Use code-block directive for standalone commands

* Correct options in key generation command

* Correct incorrect indent

* Fix syntax error

* Correct compatibility and grammar in PIV logon guide
diff --git a/source/components/nitrokeys/features/piv/access_control.rst b/source/components/nitrokeys/features/piv/access_control.rst
@@ -39,7 +39,7 @@ The factory default for the *PIN* is ``123456``.
    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``.
+2. On the terminal enter ``nitropy nk3 piv --experimental change-pin``.
 
 
 Personal Unblocking Key (PUK)
@@ -57,7 +57,7 @@ The factory default for the *PUK* is ``123456``.
    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``.
+2. On the terminal enter ``nitropy nk3 piv --experimental change-puk``.
 
 
 Retry Counter
@@ -70,11 +70,11 @@ 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``.
+To unblock the *PIN*, use the command ``nitropy nk3 piv --experimental 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.
+If these attempts are used up, the PIV smart 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.
 
 
@@ -84,6 +84,6 @@ 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 authentication is done with ``nitropy nk3 piv --experimental admin-auth``.
 
-The management key can be changed with ``nitropy nk3 piv change-admin-key``.
+The management key can be changed with ``nitropy nk3 piv --experimental change-admin-key``.
diff --git a/source/components/nitrokeys/features/piv/certificate_management.rst b/source/components/nitrokeys/features/piv/certificate_management.rst
@@ -14,16 +14,16 @@ 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>``
+    nitropy nk3 piv --experimental read-certificate --key <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>
+    nitropy nk3 piv --experimental write-certificate --key <key-slot>
diff --git a/source/components/nitrokeys/features/piv/factory_reset.rst b/source/components/nitrokeys/features/piv/factory_reset.rst
@@ -3,14 +3,14 @@ Factory Reset
 
 .. product-table:: nk3
 
-The PIV application can be reset to factory defaults.
+The PIV smart card 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.
+   Performing a factory reset of the PIV smart card will delete all private keys and certificates.
 
 The reset to factory defaults can be performed as follows.
 
-::
+.. code-block::
 
-    nitropy nk3 piv factory-reset
+    nitropy nk3 piv --experimental factory-reset
diff --git a/source/components/nitrokeys/features/piv/guides/client_logon_with_active_directory.rst b/source/components/nitrokeys/features/piv/guides/client_logon_with_active_directory.rst
@@ -3,7 +3,7 @@ Client Logon with Active Directory
 
 .. product-table:: nk3
 
-This document explains how to use the PIV application of a Nitrokey 3 for smartcard logon with Active Directory. It is available as of firmware version 1.8 and higher.
+This document explains how to use the PIV smart card of a Nitrokey 3 for logon with Active Directory. It is available as of firmware version 1.8 and higher.
 
 In the future, this manual provisioning may be automated through a Windows MiniDriver.
 
@@ -13,14 +13,14 @@ Prerequisites
 The setup requires administrative access to the machines running Active Directory Directory Services (ADDS) and Active Directory Certificate Services (ADCS).
 On the client machine only access to the respective user account used for logon is required.
 
-* Windows server (supported versions are Windows Server 2016, 2019, 2022 in all editions)
+* Windows server (supported versions are Windows Server 2016, 2019, 2022, 2025 in Standard and Enterprise editions)
    * ADDS role installed and configured.
    * ADCS role installed and *Enterprise-CA* with root certificate configured.
       * Each Domain Controller (DC) must have a *Domain Controller*, *Domain Controller Authentication*, and *Kerberos Authentication* certificate issued.
       * If you have clients leaving the company network, make sure the published full and delta certificate revocation lists (CRL) are retrievable from external networks.
 * Windows client (supported versions are Windows 10, 11 in editions *Professional* and *Enterprise*)
    * Client must be a domain member of the Active Directory (AD) domain.
-* Nitrokey 3 with PIV application.
+* Nitrokey 3 with PIV smart card.
 
 Configure smartcard logon for use with Active Directory (AD)
 ------------------------------------------------------------
@@ -58,7 +58,7 @@ It is used to sign the Certificate Request (CSR) during provisioning of the Nitr
 
                   .. important::
                      Microsoft recommends to use the RSA algorithm with a key length of ``2048`` Bit.
-                     If you choose to use Eliptic Curve (EC) keys you need to make additional changes on your client computers.
+                     If you choose to use Elliptic Curve (EC) keys you need to make additional changes on your client computers.
 
             **Subject Name**
                * Set **Supply in the request**.
@@ -77,29 +77,28 @@ It is used to sign the Certificate Request (CSR) during provisioning of the Nitr
 Provision Nitrokey 3 for smartcard logon with Active Directory
 --------------------------------------------------------------
 
-The smartcard logon requires to provision a Nitrokey for an user in Active Directory.
-The provisiong contains the private key and Certificate Singing Request (CSR) generation.
+The smartcard logon requires to provision a Nitrokey for a user in Active Directory.
+The provisioning contains the private key and Certificate Singing Request (CSR) generation.
 The certificate is then written to the Nitrokey.
 
 .. warning::
    Before following the steps below make sure the Active Directory user account you want to use for smartcard logon exists.
    A creation time of the certificate before the creation time of the user account will lead to a failed logon.
 
-.. important::
-   If the PIV application on the Nitrokey was not used before, perform a initialization with ``nitropy nk3 piv init`` first.
-
 1. Generate a private key and write the CSR to file with the command below.
 
-   ::
+   .. code-block::
 
-      nitropy nk3 piv generate-key --key 9A --algo <algorithm> --subject-name <subject-name> --subject-alt-name-upn <subject-alternative-name> --out-file <file>
+      nitropy nk3 piv --experimental generate-key --key 9A --algo <algorithm> --subject-name <subject-name> --subject-alt-name-upn <subject-alternative-name> --path <file>
 
    The value of ``<algorithm>`` is the used algorithm with its key length, e.g. ``rsa2048``.
-   The values of ``<subject-name>`` and ``<subject-alternative-name>`` corresponds typically to the ``commonName`` and ``userPrincipalName`` attribute of the Active Directory user account.
+   The value of ``<subject-name>`` corresponds to the value of the ``distinguishedName`` attribute of the Active Directory user account.
+   In most cases it is only necessary to include the common name part of the distinguished name, e.g. ``CN=John Doe``.
+   The value of ``<subject-alternative-name>`` corresponds to the value of the ``userPrincipalName`` attribute of the Active Directory user account.
 
 2. Sign the CSR with the certificate authority (CA) of the domain with the command below.
 
-   ::
+   .. code-block::
 
       certreq -attrib CertificateTemplate:<template-name> -submit <file>
    
@@ -108,12 +107,58 @@ The certificate is then written to the Nitrokey.
 
 3. Write the signed certificate to the Nitrokey with the command below.
 
-   ::
+   .. code-block::
 
-      nitropy nk3 piv write-certificate --format PEM --path <file>
+      nitropy nk3 piv --experimental write-certificate --key 9A --format PEM --path <file>
 
    The value of ``<file>`` is the certificate file.
 
+4. Map the certificate with the Active Directory user account.
+   Create the certificate mappings with the command below.
+
+   .. code-block::
+
+      nitropy nk3 piv --experimental get-windows-auth-mapping
+
+   Choose one of the offered certificate mappings.
+
+   .. tip::
+      Microsoft recommends the use of the ``X509IssuerSerialNumber`` mapping.
+
+   Write the choosen mapping to the ``altSecurityIdentities`` attribute of the Active Directory user object.
+   You can use the *Active Directory Users and Computers* application or PowerShell for this operation.
+
+   .. tabs::
+      .. tab:: Active Directory Users and Computers
+         1. From the Command Line, PowerShell, or Run, type ``dsa.msc`` and press Enter.
+         2. In the menu bar click **View → Advanced Features**.
+         3. Select the respective user object.
+         4. In the menu bar click **Action → Properties**.
+         5. Open the tab **Attribute Editor**.
+         6. Select the attribute ``altSecurityIdentities``.
+         7. Click on **Edit**.
+         8. Insert the certificate mapping in the text field and click **Add**.
+         9. Apply the change with a click on **OK**.
+
+      .. tab:: PowerShell
+         1. Open PowerShell.
+         2. Add the value with ``Set-ADUser -Identity "<sAMAccountName>" -Add @{altSecurityIdentities="<certificate-mapping>"}``, replacing ``<sAMAccountName>`` with the value of the user logon name and ``<certificate-mapping>`` with the choosen certficate mapping from above.
+
+   .. important::
+      If the certificate mapping is not correctly set you will receive the error message ``Logon screen message: Your credentials could not be verified.`` when attempting to logon.
+      Additionally, you will see the event message below in the Windows system event log.
+
+      **Source**
+
+      ::
+
+         Kerberos-Key-Distribution-Center
+
+      **Message**
+
+      ::
+
+         The Key Distribution Center (KDC) encountered a user certificate that was valid but could not be mapped to a user in a secure way (such as via explicit mapping, key trust mapping, or a SID). Such certificates should either be replaced or mapped directly to the user via explicit mapping. See https://go.microsoft.com/fwlink/?linkid=2189925 to learn more.
 
 Revoke smartcard logon for use with Active Directory (AD)
 ---------------------------------------------------------
@@ -167,5 +212,5 @@ In certain situations this is a required procedure.
    .. tab:: PowerShell
       1. Make sure you are logged on to the user account the certificate corresponds to.
       2. Open PowerShell.
-      3. Change to the personal certficate store of the user with ``Set-Location -Path cert:\CurrentUser\My``.
-      4. Import the certificate to the store with ``Import-Certificate -Filepath '<path>'``, replacing ``<path>`` with the certificate file path.
+      3. Import the certificate with ``Import-Certificate -CertStoreLocation Cert:\CurrentUser\My -FilePath <path>``, replacing ``<file>`` with the certificate file path.
+      4. After the import completed check for the certificate with ``Get-ChildItem Cert:\CurrentUser\My``.
diff --git a/source/components/nitrokeys/features/piv/index.rst b/source/components/nitrokeys/features/piv/index.rst
@@ -3,7 +3,7 @@ PIV (Personal Identity Verification)
 
 .. product-table:: nk3
 
-The *Personal Identity Verfication* (PIV) is based on the NIST special publication `SP 800-73 <https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-73-4.pdf>`__.
+The *Personal Identity Verfication* (PIV) smart card is based on the NIST special publication `SP 800-73 <https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-73-4.pdf>`__.
 It is available as of firmware version 1.8 and higher.
 
 .. toctree::
diff --git a/source/components/nitrokeys/features/piv/key_management.rst b/source/components/nitrokeys/features/piv/key_management.rst
@@ -35,7 +35,7 @@ For each purpose the private key and its corresponding certificate are stored in
 Algorithms
 ----------
 
-PIV uses asymmetric and symmetric algorithms. The asymmetric algorithms are used for the user private keys and the symmetric algorithms for the management key.
+The PIV smart card 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:
 
@@ -57,15 +57,15 @@ For compatibility reasons, the default management key is the following 3DES (TDE
 
 ::
 
-    0102030405060708 0102030405060708 0102030405060708 
+   0102030405060708 0102030405060708 0102030405060708 
 
 Key Generation
 --------------
 
 The PIV smart card can generate a new private key on the Nitrokey.
 
-The command below will create a private key in key slot ``9a`` for the user with the subject name ``John Doe`` and subject alternative name ``jd@nitrokey.local``.
+The command below will create a private key in key slot ``9a`` with the RSA algorithm and a key length of 2048 bit, for the user with the subject name ``CN=John Doe`` and subject alternative name ``jd@nitrokey.local``.
 
-::
+.. code-block::
 
-   nitropy nk3 piv generate-key --key-slot 9a --subject-name "John Doe" --subject-alt-name-upn "jd@nitrokey.local"
+   nitropy nk3 piv --experimental generate-key --key 9a --algo rsa2048 --subject-name "CN=John Doe" --subject-alt-name-upn "jd@nitrokey.local" --path jd.csr
diff --git a/source/components/nitrokeys/nitrokey3/set-pins.rst b/source/components/nitrokeys/nitrokey3/set-pins.rst
@@ -168,7 +168,7 @@ It is useful in situations when the user of the Nitrokey should be able to unblo
 PIV
 ---
 
-The *PIN* and *PUK* for PIV (Personal Identity Verification) Card can be set with `pivy-tool <https://github.com/arekinath/pivy>`__.
+The *PIN* and *PUK* for PIV (Personal Identity Verification) card can be set with `nitropy <https://github.com/nitrokey/pynitrokey>`__.
 
 PIN
 ^^^
@@ -185,7 +185,7 @@ The factory default for the *PIN* is ``123456``.
     If this attempts are used up, the *PIN* must be unlocked with the *PUK*.
 
 1. Connect the Nitrokey 3 with your computer.
-2. On the terminal enter ``pivy-tool change-pin``.
+2. On the terminal enter ``nitropy nk3 piv --experimental change-pin``.
 
 PUK
 ^^^
@@ -202,6 +202,6 @@ The factory default for the *PUK* is ``123456``.
     If this attempts are used up, the PIV Card can not be used anymore and must be reset to factory defaults.
 
 1. Connect the Nitrokey 3 with your computer.
-2. On the terminal enter ``pivy-tool change-puk``.
+2. On the terminal enter ``nitropy nk3 piv --experimental change-puk``.
 
 .. end-piv-card
