usr/src/man/man5/pkcs11_tpm.5

   1 '\" te
   2 .\"  Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   4 .\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with
   5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH PKCS11_TPM 5 "Mar 20, 2009"
   7 .SH NAME
   8 pkcs11_tpm \- RSA PKCS#11 token for Trusted Platform Modules (TPM)
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 /usr/lib/security/pkcs11_tpm.so
  13 .fi
  14
  15 .LP
  16 .nf
  17 /usr/lib/security/64/pkcs11_tpm.so
  18 .fi
  19
  20 .SH DESCRIPTION
  21 .sp
  22 .LP
  23 The \fBpkcs11_tpm.so\fR object implements the RSA PKCS#11 v2.20 specification
  24 using Trusted Computing Group protocols to talk to a TPM security device. This
  25 provider implements the PKCS#11 specification and uses the TCG Software Stack
  26 (TSS) APIs in the \fBSUNWtrousers\fR package.
  27 .sp
  28 .LP
  29 Application developers should link to \fBlibpkcs11.so.1\fR rather than link
  30 directly with \fBpkcs11_tpm.so\fR. See \fBlibpkcs11\fR(3LIB).
  31 .sp
  32 .LP
  33 The following cryptographic algorithms are implemented: \fBRSA\fR, \fBSHA1\fR,
  34 and \fBMD5\fR.
  35 .sp
  36 .LP
  37 All of the standard PKCS#11 functions listed in \fBlibpkcs11\fR(3LIB) are
  38 implemented except for the following:
  39 .sp
  40 .in +2
  41 .nf
  42 C_EncryptUpdate
  43 C_EncryptFinal
  44 C_DecryptUpdate
  45 C_DecryptFinal
  46 C_DigestEncryptUpdate
  47 C_DecryptDigestUpdate
  48 C_SignEncryptUpdate
  49 C_DecryptVerifyUpdate
  50 C_GetFunctionStatus
  51 C_CancelFunction
  52 C_WaitForSlotEvent
  53 C_GenerateKey
  54 C_DeriveKey
  55 .fi
  56 .in -2
  57 .sp
  58
  59 .sp
  60 .LP
  61 The following RSA PKCS#11 v2.20 mechanisms are supported:
  62 .sp
  63 .in +2
  64 .nf
  65 CKM_RSA_PKCS_KEY_PAIR_GEN
  66 CKM_RSA_PKCS
  67 CKM_RSA_PKCS_OAEP
  68 CKM_RSA_X_509
  69 CKM_MD5_RSA_PKCS
  70 CKM_SHA1_RSA_PKCS
  71 CKM_SHA_1
  72 CKM_SHA_1_HMAC
  73 CKM_SHA_1_HMAC_GENERAL
  74 CKM_MD5
  75 CKM_MD5_HMAC
  76 CKM_MD5_HMAC_GENERAL
  77 .fi
  78 .in -2
  79 .sp
  80
  81 .SS "Per-User Initialization"
  82 .sp
  83 .LP
  84 The \fBpkcs11_tpm\fR provider can only be used on a system which has a TPM
  85 device and which also has the \fBSUNWtrousers\fR package installed. If those
  86 prerequisites are met, users can create their own private tokens using
  87 \fBpktool\fR(1), which will allow them to perform operations using the TPM
  88 device and protect their private data with TPM-protected keys.
  89 .sp
  90 .LP
  91 To prepare and initialize a user's TPM token, the following steps must be
  92 performed:
  93 .RS +4
  94 .TP
  95 1.
  96 Initialize the token.
  97 .RE
  98 .RS +4
  99 .TP
 100 2.
 101 Set the SO (security officer) PIN.
 102 .RE
 103 .RS +4
 104 .TP
 105 3.
 106 Set the user's unique PIN.
 107 .RE
 108 .sp
 109 .LP
 110 Initializing the token is done using the \fBpktool\fR(1) command as follows:
 111 .sp
 112 .in +2
 113 .nf
 114 $ \fBpktool inittoken currlabel=TPM newlabel=tpm/myname\fR
 115 .fi
 116 .in -2
 117 .sp
 118
 119 .RS +4
 120 .TP
 121 .ie t \(bu
 122 .el o
 123 By default, an uninitialized TPM is recognized by the name \fBTPM\fR. When a
 124 user initializes their own private token, it can either be renamed to something
 125 else (for example, \fBtpm/joeuser\fR) or kept as \fBTPM\fR (in which case the
 126 \fBnewlabel\fR argument would be omitted).
 127 .RE
 128 .RS +4
 129 .TP
 130 .ie t \(bu
 131 .el o
 132 The user will have to supply the default SO PIN before being able to initialize
 133 his or her token. The default SO PIN is \fB87654321\fR. It is changed in step
 134 2, above.
 135 .RE
 136 .sp
 137 .LP
 138 Once the token is initialized, the SO and user PINs must be changed from the
 139 default values. Again, \fBpktool\fR(1) is used to change these PIN values.
 140 .sp
 141 .LP
 142 Changing the SO PIN:
 143 .sp
 144 .in +2
 145 .nf
 146 $ \fBpktool setpin token=tpm/joeuser so\fR
 147 .fi
 148 .in -2
 149 .sp
 150
 151 .sp
 152 .LP
 153 The \fBso\fR option indicates that this "setpin" operation is to change the SO
 154 PIN and must be present. The user must then enter the default SO PIN
 155 (\fB87654321\fR) and then enter (and confirm) a new PIN.
 156 .sp
 157 .LP
 158 Once the SO PIN is reset from the default, the user's unique PIN must also be
 159 changed.
 160 .sp
 161 .LP
 162 Changing the user's PIN:
 163 .sp
 164 .in +2
 165 .nf
 166 $ \fBpktool setpin token=tmp/joeuser\fR
 167 .fi
 168 .in -2
 169 .sp
 170
 171 .sp
 172 .LP
 173 The default PIN for a non-SO user is \fB12345678\fR. The user must enter the
 174 default PIN and then enter (and confirm) a new, unique PIN.
 175 .sp
 176 .LP
 177 The PIN provided for the \fBpktool\fR \fBsetpin\fR operation or by calling
 178 \fBC_Login()\fR and \fBC_SetPIN()\fR functions can be any string of characters
 179 with a length between 1 and 256 and no embedded nulls.
 180 .SS "Accessing the Token"
 181 .sp
 182 .LP
 183 After a user initializes their token, they can begin using it with
 184 \fBpktool\fR(1) or by writing PKCS11 applications and locating the token using
 185 the name created above (\fBtpm/joeuser\fR in the examples above).
 186 .sp
 187 .LP
 188 Examples:
 189 .sp
 190 .in +2
 191 .nf
 192 $ \fBpktool gencert token=tpm/joeuser -i\fR
 193 $ \fBpktool list token=tpm/joeuser\fR
 194 .fi
 195 .in -2
 196 .sp
 197
 198 .SS "Notes"
 199 .sp
 200 .LP
 201 \fBpkcs11_tpm.so\fR provides object storage in a filesystem-specific token
 202 object storage area. Private objects are protected by encryption with private
 203 keys and can only be decrypted by loading the token's private key into the TPM
 204 and performing the decryption entirely in the TPM. The user's private key is
 205 generated by the TPM when the user sets their personal PIN (see above). The
 206 keys for both the SO and users are stored in the TSS persistent storage
 207 database and are referenced by a unique UUID value. All user tokens have a
 208 unique SO key and unique user key so that the PINs for one user's token will
 209 not unlock private data in another user's token on the same machine.
 210 .sp
 211 .LP
 212 Each TPM is unique and the token keys created on one TPM may not be used on
 213 another TPM. The \fBpkcs11_tpm.so\fR token data is all managed on the system
 214 where the TPM resides and may not be moved to other systems. If the TPM is
 215 reset and the SRK (Storage Root Key) is changed, all of the keys previously
 216 generated for that TPM will no longer be valid.
 217 .sp
 218 .LP
 219 \fBpkcs11_tpm.so\fR creates a private workspace to manage administrative files
 220 for each token created. By default, this area is created as
 221 \fB/var/tpm/pkcs11/$USERNAME\fR. However, users may override this by setting
 222 the \fBPKCS11_TPM_DIR\fR environment variable prior to initializing or using
 223 the token.
 224 .SH RETURN VALUES
 225 .sp
 226 .LP
 227 The return values for each of the implemented functions are defined and listed
 228 in the RSA PKCS#11 v2.20 specification. See \fBhttp://www.rsasecurity.com\fR.
 229 .SH FILES
 230 .sp
 231 .ne 2
 232 .na
 233 \fB\fB/var/tpm/pkcs11/USERNAME\fR\fR
 234 .ad
 235 .sp .6
 236 .RS 4n
 237 User's default token object store.
 238 .RE
 239
 240 .sp
 241 .ne 2
 242 .na
 243 \fB\fB${PKCS11_TPM_DIR}\fR\fR
 244 .ad
 245 .sp .6
 246 .RS 4n
 247 Alternate token object store.
 248 .RE
 249
 250 .SH ATTRIBUTES
 251 .sp
 252 .LP
 253 See \fBattributes\fR(5) for descriptions of the following attributes:
 254 .sp
 255
 256 .sp
 257 .TS
 258 box;
 259 c | c
 260 l | l .
 261 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 262 _
 263 Interface Stability     Committed
 264 _
 265 MT-Level        MT-Safe with Exceptions (see below)
 266 _
 267 Standard        PKCS#11 v2.20
 268 .TE
 269
 270 .sp
 271 .LP
 272 Exceptions to MT-Safe attribute are documented in section 6.5.2 of RSA PKCS#11
 273 v2.20.
 274 .SH SEE ALSO
 275 .sp
 276 .LP
 277 \fBpktool\fR(1), \fBcryptoadm\fR(1M), \fBlibpkcs11\fR(3LIB),
 278 \fBattributes\fR(5)
 279 .sp
 280 .LP
 281 TCG Software Stack (TSS) Specifications: \fBhttps://www.trustedcomputinggroup.
 282 org/specs/TSS\fR (as of the date of publication)