Manual Pages for UNIX Operating System command usage for man pkcs11_tpm

Standards, Environments, and Macros                 pkcs11_tpm(5)



NAME
     pkcs11_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



SunOS 5.11          Last change: 20 Mar 2009                    1






Standards, Environments, and Macros                 pkcs11_tpm(5)



       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  some-
              thing  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.






SunOS 5.11          Last change: 20 Mar 2009                    2






Standards, Environments, and Macros                 pkcs11_tpm(5)



     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 con-
     firm) 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  cal-
     ling 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





SunOS 5.11          Last change: 20 Mar 2009                    3






Standards, Environments, and Macros                 pkcs11_tpm(5)



  Notes
     pkcs11_tpm.so  provides  object  storage  in  a  filesystem-
     specific token object storage area. Private objects are pro-
     tected 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 data-
     base 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 adminis-
     trative  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.rsasecurity.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  attri-
     butes:







SunOS 5.11          Last change: 20 Mar 2009                    4






Standards, Environments, and Macros                 pkcs11_tpm(5)



     ___________________________________________________________________
    |       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 ALSO
     pktool(1), cryptoadm(1M), libpkcs11(3LIB), attributes(5)


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

































SunOS 5.11          Last change: 20 Mar 2009                    5