Smart Card integration

This document is for:

Invicti Platform

If your target's login process is protected with PKCS #11 smart card authentication, you can implement this functionality into your Invicti Platform installation on your internal Agent Windows installation.

This document provides instructions on how to add PKCS #11 smart card login functionality to your targets.

Steps to enable PKCS #11 smart card functionality

Add necessary Environment Variables from a command prompt with administrative privileges:

REG ADD "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v INVICTI_PKCS11_MODULE /t REG_SZ /d "C:\Program Files\Yubico\Yubico PIV Tool\bin\libykcs11.dll" /f

REG ADD "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v INVICTI_PKCS11_PIN /t REG_SZ /d "123456" /f

🛠️	Where: INVICTI_PKCS11_MODULE variable will contain the path of your PKCS #11 driver INVICTI_PKCS11_PIN variable will contain your PIN

If you need to use specific KEY and CERT files with your smart card, you can add the following additional commands:

REG ADD "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v INVICTI_PKCS11_KEY /t REG_SZ /d "pkcs11:object=Private key for PIV Authentication;type=private" /f

REG ADD "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v INVICTI_PKCS11_CERT /t REG_SZ /d "pkcs11:object=X.509 Certificate for PIV Authentication;type=cert" /f

🛠️	Where: INVICTI_PKCS11_KEY and INVICTI_PKCS11_CERT variables will contain the standard text values for PIV authentication; typically, you will not need to make any changes to these values

Restart the machine.

NOTES ABOUT KEY AND CERTIFICATE MATCHING

When a client certificate is requested and PKCS #11 is configured, the engine selects the key/certificate using the following criteria:

Specified Key or Certificate:

If either INVICTI_PKCS11_KEY or INVICTI_PKCS11_CERT is specified, the engine attempts to load it
If only one of these is provided, the engine tries to find the matching pair automatically
If the specified certificate or key cannot be found, the process fails

Automatic Detection (If no key or certificate is specified) - The engine automatically identifies the client certificate and its associated private key based on:

Matching the server's list of acceptable Certificate Authorities (CAs) with the certificate issuer
Matching the server hostname with the certificate's Subject Alternative Name (SAN) or Common Name (CN) using OpenSSL's X509_check_host
Matching the server IP address with the certificate's IP address using OpenSSL's X509_check_ip_asc
If multiple certificates on the smart card match, the first one is used

Steps to disable PKCS #11 smartcard functionality

Remove the previously added Environment Variables from a command prompt with administrative privileges:

REG DELETE "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v INVICTI_PKCS11_MODULE /f

REG DELETE "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v INVICTI_PKCS11_PIN /f

REG DELETE "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v INVICTI_PKCS11_KEY /f

REG DELETE "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v INVICTI_PKCS11_CERT /f

Restart the machine.