pkcs11_tpm(5) Standards, Environments, and Macros pkcs11_tpm(5)NAMEpkcs11_tpm - RSA PKCS#11 token for Trusted Platform Modules (TPM)
SYNOPSIS
/usr/lib/security/pkcs11_tpm.so
/usr/lib/security/64/pkcs11_tpm.so
DESCRIPTION
The pkcs11_tpm.so object implements the RSA PKCS#11 v2.20 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 SUNWtrousers 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:
C_EncryptUpdate
C_EncryptFinal
C_DecryptUpdate
C_DecryptFinal
C_DigestEncryptUpdate
C_DecryptDigestUpdate
C_SignEncryptUpdate
C_DecryptVerifyUpdate
C_GetFunctionStatus
C_CancelFunction
C_WaitForSlotEvent
C_GenerateKey
C_DeriveKey
The following RSA PKCS#11 v2.20 mechanisms are supported:
CKM_RSA_PKCS_KEY_PAIR_GEN
CKM_RSA_PKCS
CKM_RSA_PKCS_OAEP
CKM_RSA_X_509
CKM_MD5_RSA_PKCS
CKM_SHA1_RSA_PKCS
CKM_SHA_1
CKM_SHA_1_HMAC
CKM_SHA_1_HMAC_GENERAL
CKM_MD5
CKM_MD5_HMAC
CKM_MD5_HMAC_GENERAL
Per-User Initialization
The pkcs11_tpm provider can only be used on a system which has a TPM
device and which also has the SUNWtrousers package installed. 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
o 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).
o 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).
Examples:
$ pktool gencert token=tpm/joeuser -i
$ pktool list token=tpm/joeuser
Notes
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/tpm/pkcs11/$USERNAME. 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 RSA PKCS#11 v2.20 specification. See http://www.rsasecu‐
rity.com.
FILES
/var/tpm/pkcs11/USERNAME
User's default token object store.
${PKCS11_TPM_DIR}
Alternate token object store.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬────────────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼────────────────────────────────────┤
│Interface Stability │Committed │
├─────────────────────────────┼────────────────────────────────────┤
│MT-Level │MT-Safe with Exceptions (see below) │
├─────────────────────────────┼────────────────────────────────────┤
│Standard │PKCS#11 v2.20 │
└─────────────────────────────┴────────────────────────────────────┘
Exceptions to MT-Safe attribute are documented in section 6.5.2 of RSA
PKCS#11 v2.20.
SEE ALSOpktool(1), cryptoadm(1M), libpkcs11(3LIB), attributes(5)
TCG Software Stack (TSS) Specifications: https://www.trustedcomputing‐
group. org/specs/TSS (as of the date of publication)
SunOS 5.11 20 Mar 2009 pkcs11_tpm(5)
