pkcs11_tpm(5)

1pkcs11_tpm(5)         Standards, Environments, and Macros        pkcs11_tpm(5)
2
3
4

NAME

6       pkcs11_tpm - RSA PKCS#11 token for Trusted Platform Modules (TPM)
7

SYNOPSIS

9       /usr/lib/security/pkcs11_tpm.so
10
11
12       /usr/lib/security/64/pkcs11_tpm.so
13
14

DESCRIPTION

16       The pkcs11_tpm.so object implements the RSA PKCS#11 v2.20 specification
17       using Trusted Computing Group protocols  to  talk  to  a  TPM  security
18       device. This provider implements the PKCS#11 specification and uses the
19       TCG Software Stack (TSS) APIs in the SUNWtrousers package.
20
21
22       Application developers should link to libpkcs11.so.1 rather  than  link
23       directly with pkcs11_tpm.so. See libpkcs11(3LIB).
24
25
26       The  following cryptographic algorithms are implemented: RSA, SHA1, and
27       MD5.
28
29
30       All of the standard PKCS#11 functions  listed  in  libpkcs11(3LIB)  are
31       implemented except for the following:
32
33         C_EncryptUpdate
34         C_EncryptFinal
35         C_DecryptUpdate
36         C_DecryptFinal
37         C_DigestEncryptUpdate
38         C_DecryptDigestUpdate
39         C_SignEncryptUpdate
40         C_DecryptVerifyUpdate
41         C_GetFunctionStatus
42         C_CancelFunction
43         C_WaitForSlotEvent
44         C_GenerateKey
45         C_DeriveKey
46
47
48
49
50       The following RSA PKCS#11 v2.20 mechanisms are supported:
51
52         CKM_RSA_PKCS_KEY_PAIR_GEN
53         CKM_RSA_PKCS
54         CKM_RSA_PKCS_OAEP
55         CKM_RSA_X_509
56         CKM_MD5_RSA_PKCS
57         CKM_SHA1_RSA_PKCS
58         CKM_SHA_1
59         CKM_SHA_1_HMAC
60         CKM_SHA_1_HMAC_GENERAL
61         CKM_MD5
62         CKM_MD5_HMAC
63         CKM_MD5_HMAC_GENERAL
64
65
66
67   Per-User Initialization
68       The  pkcs11_tpm  provider  can only be used on a system which has a TPM
69       device and which also has the SUNWtrousers package installed. If  those
70       prerequisites  are met, users can create their own private tokens using
71       pktool(1), which will allow them to perform operations  using  the  TPM
72       device and protect their private data with TPM-protected keys.
73
74
75       To  prepare and initialize a user's TPM token, the following steps must
76       be performed:
77
78           1.     Initialize the token.
79
80           2.     Set the SO (security officer) PIN.
81
82           3.     Set the user's unique PIN.
83
84
85       Initializing the token is done using the pktool(1) command as follows:
86
87         $ pktool inittoken currlabel=TPM newlabel=tpm/myname
88
89
90
91           o      By default, an uninitialized TPM is recognized by  the  name
92                  TPM. When a user initializes their own private token, it can
93                  either  be  renamed  to   something   else   (for   example,
94                  tpm/joeuser)  or  kept  as  TPM  (in which case the newlabel
95                  argument would be omitted).
96
97           o      The user will have to supply the default SO PIN before being
98                  able  to  initialize his or her token. The default SO PIN is
99                  87654321. It is changed in step 2, above.
100
101
102       Once the token is initialized, the SO and user  PINs  must  be  changed
103       from  the  default values. Again, pktool(1) is used to change these PIN
104       values.
105
106
107       Changing the SO PIN:
108
109         $ pktool setpin token=tpm/joeuser so
110
111
112
113
114       The so option indicates that this "setpin" operation is to  change  the
115       SO PIN and must be present. The user must then enter the default SO PIN
116       (87654321) and then enter (and confirm) a new PIN.
117
118
119       Once the SO PIN is reset from the default, the user's unique  PIN  must
120       also be changed.
121
122
123       Changing the user's PIN:
124
125         $ pktool setpin token=tmp/joeuser
126
127
128
129
130       The  default PIN for a non-SO user is 12345678. The user must enter the
131       default PIN and then enter (and confirm) a new, unique PIN.
132
133
134       The PIN  provided  for  the  pktool  setpin  operation  or  by  calling
135       C_Login() and C_SetPIN() functions can be any string of characters with
136       a length between 1 and 256 and no embedded nulls.
137
138   Accessing the Token
139       After a user initializes their token, they  can  begin  using  it  with
140       pktool(1)  or  by  writing  PKCS11  applications and locating the token
141       using the name created above (tpm/joeuser in the examples above).
142
143
144       Examples:
145
146         $ pktool gencert token=tpm/joeuser -i
147         $ pktool list token=tpm/joeuser
148
149
150
151   Notes
152       pkcs11_tpm.so provides object storage in  a  filesystem-specific  token
153       object  storage  area. Private objects are protected by encryption with
154       private keys and can only be decrypted by loading the  token's  private
155       key into the TPM and performing the decryption entirely in the TPM. The
156       user's private key is generated by the TPM when  the  user  sets  their
157       personal PIN (see above). The keys for both the SO and users are stored
158       in the TSS persistent storage database and are referenced by  a  unique
159       UUID value. All user tokens have a unique SO key and unique user key so
160       that the PINs for one user's token will  not  unlock  private  data  in
161       another user's token on the same machine.
162
163
164       Each  TPM  is  unique  and the token keys created on one TPM may not be
165       used on another TPM. The pkcs11_tpm.so token data is all managed on the
166       system  where the TPM resides and may not be moved to other systems. If
167       the TPM is reset and the SRK (Storage Root Key) is changed, all of  the
168       keys previously generated for that TPM will no longer be valid.
169
170
171       pkcs11_tpm.so  creates  a  private  workspace  to manage administrative
172       files for each token created. By  default,  this  area  is  created  as
173       /var/tpm/pkcs11/$USERNAME.  However, users may override this by setting
174       the PKCS11_TPM_DIR environment variable prior to initializing or  using
175       the token.
176

RETURN VALUES

178       The return values for each of the implemented functions are defined and
179       listed in the RSA PKCS#11 v2.20 specification. See  http://www.rsasecu‐
180       rity.com.
181

FILES

183       /var/tpm/pkcs11/USERNAME
184
185           User's default token object store.
186
187
188       ${PKCS11_TPM_DIR}
189
190           Alternate token object store.
191
192

ATTRIBUTES

194       See attributes(5) for descriptions of the following attributes:
195
196
197
198
199       ┌─────────────────────────────┬────────────────────────────────────┐
200       │      ATTRIBUTE TYPE         │          ATTRIBUTE VALUE           │
201       ├─────────────────────────────┼────────────────────────────────────┤
202       │Interface Stability          │Committed                           │
203       ├─────────────────────────────┼────────────────────────────────────┤
204       │MT-Level                     │MT-Safe with Exceptions (see below) │
205       ├─────────────────────────────┼────────────────────────────────────┤
206       │Standard                     │PKCS#11 v2.20                       │
207       └─────────────────────────────┴────────────────────────────────────┘
208
209
210       Exceptions  to MT-Safe attribute are documented in section 6.5.2 of RSA
211       PKCS#11 v2.20.
212

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

FILES

ATTRIBUTES

SEE ALSO