Normally Group Policy triggers Certificate Autoenrollment. If you are not using Group Policy, use the vascert command line utility to manually trigger Certificate Autoenrollment processing for the machine. This will result in certificates being added to the System.keychain according to enrollment policy. You can schedule this command to run periodically if desired.
To manually trigger Certificate Autoenrollment
-
Log in as a root user or using sudo.
-
To manually trigger Certificate Autoenrollment, run the following command:
/opt/quest/bin/vascert trigger
Certificate Autoenrollment will proceed in the background. When complete, newly enrolled certificates will be installed in the System.keychain automatically. To troubleshoot Certificate Autoenrollment, run the vascert pulse command as root.
Certificate autoenrollment on Linux can store and safeguard certificates and keys in either of the following ways:
Based on the cryptographic provider set in the certificate template, vascert decides where to store the keys and certificates. If the cryptographic provider set in the certificate template is the Microsoft Platform Crypto Provider, then the keys and the certificates will be stored and protected by TPM, otherwise by p12 files. This property can be set in each certificate template, so it is possible to store certain certificates in TPM and others in p12 files. The picture below shows a certificate template set to Microsoft Platform Crypto Provider, so the certificates created by this template will be stored and protected by TPM.
Most of the Certificate Autoenrollment (CA) code is implemented in Java. After this code has successfully requested a certificate from a CA, it invokes platform-specific code to store the private key and certificate in a suitable way for the operating system or for particular applications. This platform-specific code is implemented as a shell script, certstore.sh, in the /var/opt/quest/vascert/script directory.
The certstore.sh script is a platform-agnostic front end that chooses and loads a platform-specific back end script:
-
For macOS, the backend script is certstore-mac.sh.
-
For Linux, the backend script is certstore-openssl.sh.
This script provides an implementation that simply stores the private keys and certificates in p12 files on the file system because there is no system keychain that is supported by all Linux distributions.
To use the certificates and keys stored in p12 files, you must enter the name and path of the p12 files into the configuration files of those programs which you want to use.
Machine certificates are stored under:
/var/opt/quest/vascert/.com.quest.X509Enrollment/certstore
User certificates are stored under:
$HOME/.com.quest.X509Enrollment/certstore
vascert creates p12 files protected by passwords. You must set the passwords in the opensslPassPhrase parameter for each user in the $HOME/.config/vas/vascert/vascert.cfg file.
When installing vascert, a sample configuration file vascert.cfg is created in the /var/opt/quest/vascert/samples library. It is recommended that you copy this file into the $HOME/.config/vas/vascert library, and set the password there. The vascert pulse command reads and encrypts the password that you set in the configuration file, then it returns the encrypted password into the configuration file. The encrypted file is indicated by the "encrypted:" tag. If the user wants to modify the password, then the encrypted password and the "encrypted:" tag must be replaced by the new password. The vascert pulse command will encrypt the new password when you run the command.
Requirements and setup
If you want to use the TPM chip to store and protect the certificates and keys, you must install and configure additional software packages. To install and configure the necessary components, you must run vascert configure tpm. This command will run the /var/opt/quest/vascert/script/tpm-setup.sh script under the hood. The vascert configure tpm command must be run by the root user first, then by all other users before using vascert.
The tpm-setup.sh script goes through the following steps:
-
Installs the tpm2_pkcs11 package. vascert manages TPM through this software library. For more information, see https://github.com/tpm2-software/tpm2-pkcs11.
-
Stores the path of the installed tpm2_pkcs11 shared object in the $HOME/.config/vas/vascert/pkcs11provider.cfg configuration file.
-
Installs and runs the TPM2 Access Broker & Resource Manager. For more information, see https://github.com/tpm2-software/tpm2-abrmd.
-
Sets the communication mechanism with the TPM. For more information, see https://github.com/tpm2-software/tpm2-tools/blob/master/man/common/tcti.md.
-
Installs p11tool, which is a program that allows operations on PKCS#11 smart cards and security modules. For more information, see https://www.gnutls.org/manual/html_node/p11tool-Invocation.html.
-
Installs pkcs11-tool, which is a utility for managing and using PKCS#11 security tokens. For more information, see https://htmlpreview.github.io/?https://github.com/OpenSC/OpenSC/blob/master/doc/tools/tools.html#pkcs11-tool.
-
Initializes the TPM as a PKCS#11 security token and sets the token label to "tpmtoken". For more information, see https://github.com/tpm2-software/tpm2-pkcs11/blob/master/docs/INITIALIZING.md.
-
Sets the Security Officer PIN on the security token, which is used for some token operations (token initialization, user PIN initialization, etc).
-
Sets the User PIN on the security token, which is used for authenticating users and safeguarding sensitive operations on the token. To store the certificates and keys on the security token, vascert must have the User PIN, so the tpm-setup.sh script stores the User PIN in the userPin parameter of the $HOME/.config/vas/vascert/vascert.cfg configuration file. vascert ecrypts this parameter the same way as in the case of the opensslPassPhrase parameter as described in Storing Certificates and keys in p12 files.
|
|
CAUTION: TPM can be accessed only by the root user and members of the tss group. To enable non-root users to use TPM, non-root users must be added to the tss group. |
Accesing certificates and keys
PKCS#11 security tokens as well as its protected certificates and keys can be referenced by PKCS#11 URI. For more information on PKCS#11 URI, see https://datatracker.ietf.org/doc/rfc7512/.
You can query the PKCS#11 URI for the tokens, certificates and keys using the p11tool. p11tool needs a software library through which it can manage the security tokens. TPM is managed through libtpm2_pkcs11.so software library, however, the location of the software library might vary in Linux distributions, so first you must use this command to locate the library:
$ find /usr -name libtpm2_pkcs11.so
/usr/lib/x86_64-linux-gnu/pkcs11/libtpm2_pkcs11.so
The find command will provide the path to the library on your Linux distribution. You must use this path as the value for the --provider argument every time you run the p11tool command. When initializing the security token, tpm-setup.sh sets the token label to "tpmtoken", so you can reference the token with the following PKCS#11 URI: 'pkcs11:token=tpmtoken'. Using the following command, you can query the certificates and keys from the token. For each object, this script displays the object's PKCS#11 URI after the URL tag.
# p11tool --provider='/usr/lib/x86_64-linux-gnu/pkcs11/libtpm2_pkcs11.so' --login --list-all 'pkcs11:token=tpmtoken'
Token 'tpmtoken' with URL 'pkcs11:model=SW%20%20%20TPM%00%00%00%00%00%00%00%00;manufacturer=IBM;serial=0000000000000000;token=tpmtoken' requires user PIN
Enter PIN:
Object 0:
URL: pkcs11:model=SW%20%20%20TPM%00%00%00%00%00%00%00%00;manufacturer=IBM;serial=0000000000000000;token=tpmtoken;id=%54%50%4D%32%30%30%38%52%53%41%43%6C%69%65%6E%74%57%6F%72%6B%73%74%61%74%69%6F%6E%41%75%74%68%65%6E%74%69%63%61%74%69%6F%6E;object=TPM2008RSAClientWorkstationAuthentication;type=public
Type: Public key (RSA-2048)
Label: TPM2008RSAClientWorkstationAuthentication
Flags: CKA_NEVER_EXTRACTABLE;
ID: 54:50:4d:32:30:30:38:52:53:41:43:6c:69:65:6e:74:57:6f:72:6b:73:74:61:74:69:6f:6e:41:75:74:68:65:6e:74:69:63:61:74:69:6f:6e
Object 1:
URL: pkcs11:model=SW%20%20%20TPM%00%00%00%00%00%00%00%00;manufacturer=IBM;serial=0000000000000000;token=tpmtoken;id=%54%50%4D%32%30%30%38%52%53%41%43%6C%69%65%6E%74%57%6F%72%6B%73%74%61%74%69%6F%6E%41%75%74%68%65%6E%74%69%63%61%74%69%6F%6E;type=private
Type: Private key (RSA-2048)
Label:
Flags: CKA_PRIVATE; CKA_NEVER_EXTRACTABLE;
ID: 54:50:4d:32:30:30:38:52:53:41:43:6c:69:65:6e:74:57:6f:72:6b:73:74:61:74:69:6f:6e:41:75:74:68:65:6e:74:69:63:61:74:69:6f:6e
Object 2:
URL: pkcs11:model=SW%20%20%20TPM%00%00%00%00%00%00%00%00;manufacturer=IBM;serial=0000000000000000;token=tpmtoken;id=%54%50%4D%32%30%30%38%52%53%41%53%65%72%76%65%72%57%6F%72%6B%73%74%61%74%69%6F%6E%41%75%74%68%65%6E%74%69%63%61%74%69%6F%6E;object=TPM2008RSAServerWorkstationAuthentication;type=public
Type: Public key (RSA-2048)
Label: TPM2008RSAServerWorkstationAuthentication
Flags: CKA_NEVER_EXTRACTABLE;
ID: 54:50:4d:32:30:30:38:52:53:41:53:65:72:76:65:72:57:6f:72:6b:73:74:61:74:69:6f:6e:41:75:74:68:65:6e:74:69:63:61:74:69:6f:6e
Object 3:
URL: pkcs11:model=SW%20%20%20TPM%00%00%00%00%00%00%00%00;manufacturer=IBM;serial=0000000000000000;token=tpmtoken;id=%54%50%4D%32%30%30%38%52%53%41%53%65%72%76%65%72%57%6F%72%6B%73%74%61%74%69%6F%6E%41%75%74%68%65%6E%74%69%63%61%74%69%6F%6E;type=private
Type: Private key (RSA-2048)
Label:
Flags: CKA_PRIVATE; CKA_NEVER_EXTRACTABLE;
ID: 54:50:4d:32:30:30:38:52:53:41:53:65:72:76:65:72:57:6f:72:6b:73:74:61:74:69:6f:6e:41:75:74:68:65:6e:74:69:63:61:74:69:6f:6e
Object 4:
URL: pkcs11:model=SW%20%20%20TPM%00%00%00%00%00%00%00%00;manufacturer=IBM;serial=0000000000000000;token=tpmtoken;id=%54%50%4D%32%30%30%38%52%53%41%43%6C%69%65%6E%74%57%6F%72%6B%73%74%61%74%69%6F%6E%41%75%74%68%65%6E%74%69%63%61%74%69%6F%6E;object=TPM2008RSAClientWorkstationAuthentication;type=cert
Type: X.509 Certificate (RSA-2048)
Expires: Sun Nov 16 16:10:38 2025
Label: TPM2008RSAClientWorkstationAuthentication
ID: 54:50:4d:32:30:30:38:52:53:41:43:6c:69:65:6e:74:57:6f:72:6b:73:74:61:74:69:6f:6e:41:75:74:68:65:6e:74:69:63:61:74:69:6f:6e
Object 5:
URL: pkcs11:model=SW%20%20%20TPM%00%00%00%00%00%00%00%00;manufacturer=IBM;serial=0000000000000000;token=tpmtoken;type=cert
Type: X.509 Certificate
Label:
ID:
Object 6:
URL: pkcs11:model=SW%20%20%20TPM%00%00%00%00%00%00%00%00;manufacturer=IBM;serial=0000000000000000;token=tpmtoken;id=%54%50%4D%32%30%30%38%52%53%41%53%65%72%76%65%72%57%6F%72%6B%73%74%61%74%69%6F%6E%41%75%74%68%65%6E%74%69%63%61%74%69%6F%6E;object=TPM2008RSAServerWorkstationAuthentication;type=cert
Type: X.509 Certificate (RSA-2048)
Expires: Sun Nov 16 16:10:38 2025
Label: TPM2008RSAServerWorkstationAuthentication
ID: 54:50:4d:32:30:30:38:52:53:41:53:65:72:76:65:72:57:6f:72:6b:73:74:61:74:69:6f:6e:41:75:74:68:65:6e:74:69:63:61:74:69:6f:6e
The list above shows the following:
-
Object 0: Public key related to the TPM2008RSAClientWorkstationAuthentication certificate.
-
Object 1: Private key related to the TPM2008RSAClientWorkstationAuthentication certificate.
-
Object 2: Public key related to the TPM2008RSAServerWorkstationAuthentication certificate.
-
Object 3: Private key related to the TPM2008RSAServerWorkstationAuthentication certificate.
-
Object 4: The TPM2008RSAClientWorkstationAuthentication certificate.
-
Object 5: Root-certificates for the TPM2008RSAClientWorkstationAuthentication and TPM2008RSAServerWorkstationAuthentication certificates.
-
Object 6: The TPM2008RSAServerWorkstationAuthentication certificate.
Example: Referencing certificates and keys protected by TPM
The following is an example using openssl s_server and openssl s_client programs. Both commands have a -cert and a -key argument. The references for the certificate and the key protected by TPM are entered in these two arguments.
In order for openssl to access objects protected by the TPM, the software libraries that allow access must be specified in its configuration file. In the example below, one of the libraries is the same that we used with the p11tool, the other library is the openssl pkcs11-provider module.
# apt install pkcs11-provider
$ find / -name pkcs11.so
/usr/lib/x86_64-linux-gnu/ossl-modules/pkcs11.so
$ cat openssl_provider.cnf
openssl_conf = openssl_init
[openssl_init]
providers = provider_sect
[provider_sect]
base = base_sect
default = default_sect
pkcs11 = pkcs11_sect
[base_sect]
activate = 1
[default_sect]
activate = 1
[pkcs11_sect]
module = /usr/lib/x86_64-linux-gnu/ossl-modules/pkcs11.so
pkcs11-module-path = /usr/lib/x86_64-linux-gnu/pkcs11/libtpm2_pkcs11.so
activate = 1
# OPENSSL_CONF=openssl_provider.cnf openssl s_server -accept 4443 -www -key "pkcs11:token=tpmtoken;id=%54%50%4D%32%30%30%38%52%53%41%53%65%72%76%65%72%57%6F%72%6B%73%74%61%74%69%6F%6E%41%75%74%68%65%6E%74%69%63%61%74%69%6F%6E;type=private;" -cert "pkcs11:token=tpmtoken;object=TPM2008RSAServerWorkstationAuthentication;type=cert;" -state -tls1_2 -sigalgs RSA+SHA256
# OPENSSL_CONF=openssl_provider.cnf openssl s_client -connect 127.0.0.1:4443 -CAfile sascert-CA.pem.cer -cert "pkcs11:token=tpmtoken;object=TPM2008RSAClientWorkstationAuthentication;type=cert;" -key "pkcs11:token=tpmtoken;id=%54%50%4D%32%30%30%38%52%53%41%43%6C%69%65%6E%74%57%6F%72%6B%73%74%61%74%69%6F%6E%41%75%74%68%65%6E%74%69%63%61%74%69%6F%6E;type=private" -state
