Go to main content

man pages section 7: Standards, Environments, Macros, Character Sets, and Miscellany

Exit Print View

Updated: Wednesday, January 24, 2018



pkcs11_tpm - OASIS PKCS#11 token for Trusted Platform Modules (TPM)




The pkcs11_tpm.so object implements the OASIS PKCS#11 Cryptographic Token Interface (Cryptoki), v2.40, specification using Trusted Computing Group protocols to talk to a TPM security device. This provider implements the PKCS#11 specification and uses the TCG Software Stack (TSS) APIs in the pkg:/library/security/trousers package.

Application developers should link to libpkcs11.so.1 rather than link directly with pkcs11_tpm.so. See libpkcs11(3LIB).

The following cryptographic algorithms are implemented: RSA, SHA1, and MD5.

All of the standard PKCS#11 functions listed in libpkcs11(3LIB) are implemented except for the following:


The following OASIS PKCS#11 v2.40 mechanisms are supported:



The pkcs11_tpm provider can only be used on a system which has a TPM device and which also has the pkg:/library/security/trousers package installed and the svc:/application/security/tcsd service enabled. The system administrator must also take ownership of the TPM using tpmadm(8) and enable it as a Cryptographic Framework PKCS#11 provider:

# pkg install pkcs11_tpm
# svcadm enable svc:/application/security/tcsd
# tpmadm init
Enter TPM Owner PIN:
Confirm TPM Owner PIN:
# cryptoadm install provider='/usr/lib/security/$ISA/pkcs11_tpm.so'

If those prerequisites are met, users can create their own private tokens using pktool(1), which will allow them to perform operations using the TPM device and protect their private data with TPM-protected keys.

To prepare and initialize a user's TPM token, the following steps must be performed:

  1. Initialize the token.

  2. Set the SO (security officer) PIN.

  3. Set the user's unique PIN.

Initializing the token is done using the pktool(1) command as follows:

$ pktool inittoken currlabel=TPM newlabel=tpm/myname
  • By default, an uninitialized TPM is recognized by the name TPM. When a user initializes their own private token, it can either be renamed to something else (for example, tpm/joeuser) or kept as TPM (in which case the newlabel argument would be omitted).

  • The user will have to supply the default SO PIN before being able to initialize his or her token. The default SO PIN is 87654321. It is changed in step 2, above.

Once the token is initialized, the SO and user PINs must be changed from the default values. Again, pktool(1) is used to change these PIN values.

Changing the SO PIN:

$ pktool setpin token=tpm/joeuser so

The so option indicates that this “setpin” operation is to change the SO PIN and must be present. The user must then enter the default SO PIN (87654321) and then enter (and confirm) a new PIN.

Once the SO PIN is reset from the default, the user's unique PIN must also be changed.

Changing the user's PIN:

$ pktool setpin token=tmp/joeuser

The default PIN for a non-SO user is 12345678. The user must enter the default PIN and then enter (and confirm) a new, unique PIN.

The PIN provided for the pktool setpin operation or by calling C_Login() and C_SetPIN() functions can be any string of characters with a length between 1 and 256 and no embedded nulls.

Accessing the Token

After a user initializes their token, they can begin using it with pktool(1) or by writing PKCS11 applications and locating the token using the name created above (tpm/joeuser in the examples above).


$ pktool gencert token=tpm/joeuser -i
$ pktool list token=tpm/joeuser


pkcs11_tpm.so provides object storage in a filesystem-specific token object storage area. Private objects are protected by encryption with private keys and can only be decrypted by loading the token's private key into the TPM and performing the decryption entirely in the TPM. The user's private key is generated by the TPM when the user sets their personal PIN (see above). The keys for both the SO and users are stored in the TSS persistent storage database and are referenced by a unique UUID value. All user tokens have a unique SO key and unique user key so that the PINs for one user's token will not unlock private data in another user's token on the same machine.

Each TPM is unique and the token keys created on one TPM may not be used on another TPM. The pkcs11_tpm.so token data is all managed on the system where the TPM resides and may not be moved to other systems. If the TPM is reset and the SRK (Storage Root Key) is changed, all of the keys previously generated for that TPM will no longer be valid.

pkcs11_tpm.so creates a private workspace to manage administrative files for each token created. By default, this area is created as /var/user/$USERNAME/tpm/. However, users may override this by setting the PKCS11_TPM_DIR environment variable prior to initializing or using the token.

Return Values

The return values for each of the implemented functions are defined and listed in the OASIS PKCS#11 v2.40 specification. See http://www.oasis-open.org.



User's default token object store.


Alternate token object store.


See attributes(7) for descriptions of the following attributes:

Interface Stability
MT-Safe with exceptions. See section 1.9.3 of OASIS PKCS#11 v2.40 Usage Guide
PKCS#11 v2.40

See Also

pktool(1), libpkcs11(3LIB), attributes(7), cryptoadm(8)

TCG Software Stack (TSS) Specifications, https://www.trustedcomputinggroup.org/specs/TSS (as of the date of publication)

OASIS PKCS#11 v2.40, http://www.oasis-open.org