share/man/man5/pkcs11_softtoken.5

   1 '\" te
   2 .\" Copyright (c) 2008, 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.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" 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 the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH PKCS11_SOFTTOKEN 5 "Mar 25, 2008"
   7 .SH NAME
   8 pkcs11_softtoken \- Software RSA PKCS#11 softtoken
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 /usr/lib/security/pkcs11_softtoken.so
  13 /usr/lib/security/64/pkcs11_softtoken.so
  14 .fi
  15
  16 .SH DESCRIPTION
  17 .sp
  18 .LP
  19 The \fBpkcs11_softtoken.so\fR object implements the RSA PKCS#11 v2.20
  20 specification in software. Persistent storage for "token" objects is provided
  21 by this PKCS#11 implementation.
  22 .sp
  23 .LP
  24 Application developers should link to \fBlibpkcs11.so\fR rather than link
  25 directly to \fBpkcs11_softtoken.so\fR. See \fBlibpkcs11\fR(3LIB).
  26 .sp
  27 .LP
  28 The following cryptographic algorithms are implemented: DES, 3DES, AES,
  29 Blowfish, RC4, MD5, SHA1, SHA256, SHA384, SHA512, RSA, DSA, DH, and ECC.
  30 .sp
  31 .LP
  32 All of the Standard PKCS#11 functions listed on \fBlibpkcs11\fR(3LIB) are
  33 implemented except for the following:
  34 .sp
  35 .in +2
  36 .nf
  37 C_GetObjectSize
  38 C_InitPIN
  39 C_InitToken
  40 C_WaitForSlotEvent
  41 .fi
  42 .in -2
  43
  44 .sp
  45 .LP
  46 A call to these functions returns \fBCKR_FUNCTION_NOT_SUPPORTED\fR.
  47 .sp
  48 .LP
  49 The following RSA PKCS#11 v2.20 mechanisms are supported:
  50 .sp
  51 .in +2
  52 .nf
  53 CKM_RSA_PKCS_KEY_PAIR_GEN
  54 CKM_RSA_PKCS
  55 CKM_RSA_X_509
  56
  57 CKM_DSA_KEY_PAIR_GEN
  58 CKM_DSA
  59 CKM_DSA_SHA1
  60
  61 CKM_DH_PKCS_KEY_PAIR_GEN
  62 CKM_DH_PKCS_DERIVE
  63
  64 CKM_EC_KEY_PAIR_GEN
  65 CKM_ECDSA
  66 CKM_ECDSA_SHA1
  67 CKM_ECDH1_DERIVE
  68
  69 CKM_DES_KEY_GEN
  70 CKM_DES_ECB
  71 CKM_DES_CBC
  72 CKM_DES_CBC_PAD
  73
  74 CKM_DES3_KEY_GEN
  75 CKM_DES3_ECB
  76 CKM_DES3_CBC
  77 CKM_DES3_CBC_PAD
  78
  79 CKM_AES_KEY_GEN
  80 CKM_AES_ECB
  81 CKM_AES_CBC
  82 CKM_AES_CBC_PAD
  83 CKM_AES_CTR
  84
  85 CKM_BLOWFISH_KEY_GEN
  86 CKM_BLOWFISH_CBC
  87
  88 CKM_RC4_KEY_GEN
  89 CKM_RC4
  90
  91 CKM_MD5_RSA_PKCS
  92 CKM_SHA1_RSA_PKCS
  93 CKM_SHA256_RSA_PKCS
  94 CKM_SHA384_RSA_PKCS
  95 CKM_SHA512_RSA_PKCS
  96
  97 CKM_MD5
  98 CKM_SHA_1
  99 CKM_SHA256
 100 CKM_SHA384
 101 CKM_SHA512
 102
 103 CKM_MD5_HMAC
 104 CKM_MD5_HMAC_GENERAL
 105 CKM_SHA_1_HMAC
 106 CKM_SHA_1_HMAC_GENERAL
 107 CKM_SHA256_HMAC
 108 CKM_SHA256_HMAC_GENERAL
 109 CKM_SHA384_HMAC
 110 CKM_SHA384_HMAC_GENERAL
 111
 112 CKM_MD5_KEY_DERIVATION
 113 CKM_SHA1_KEY_DERIVATION
 114 CKM_SHA256_KEY_DERIVATION
 115 CKM_SHA384_KEY_DERIVATION
 116 CKM_SHA512_KEY_DERIVATION
 117
 118 CKM_SSL3_PRE_MASTER_KEY_GEN
 119 CKM_SSL3_MASTER_KEY_DERIVE
 120 CKM_SSL3_KEY_AND_MAC_DERIVE
 121 CKM_SSL3_MASTER_KEY_DERIVE_DH
 122 CKM_TLS_PRE_MASTER_KEY_GEN
 123 CKM_TLS_MASTER_KEY_DERIVE
 124 CKM_TLS_KEY_AND_MAC_DERIVE
 125 CKM_TLS_MASTER_KEY_DERIVE_DH
 126 .fi
 127 .in -2
 128
 129 .sp
 130 .LP
 131 Each of the following types of key objects has certain token-specific
 132 attributes that are set to true by default as a result of object creation,
 133 key/key pair generation, and key derivation.
 134 .sp
 135 .ne 2
 136 .na
 137 \fBPublic key object\fR
 138 .ad
 139 .RS 22n
 140 \fBCKA_ENCRYPT\fR, \fBCKA_VERIFY\fR, \fBCKA_VERIFY_RECOVER\fR
 141 .RE
 142
 143 .sp
 144 .ne 2
 145 .na
 146 \fBPrivate key object\fR
 147 .ad
 148 .RS 22n
 149 \fBCKA_DECRYPT\fR, \fBCKA_SIGN\fR, \fBCKA_SIGN_RECOVER\fR,
 150 \fBCKA_EXTRACTABLE\fR
 151 .RE
 152
 153 .sp
 154 .ne 2
 155 .na
 156 \fBSecret key object\fR
 157 .ad
 158 .RS 22n
 159 \fBCKA_ENCRYPT\fR, \fBCKA_DECRYPT\fR, \fBCKA_SIGN\fR, \fBCKA_VERIFY\fR,
 160 \fBCKA_EXTRACTABLE\fR
 161 .RE
 162
 163 .sp
 164 .LP
 165 The following certificate objects are supported:
 166 .sp
 167 .ne 2
 168 .na
 169 \fB\fBCKC_X_509\fR\fR
 170 .ad
 171 .RS 23n
 172 For \fBCKC_X_509\fR certificate objects, the following attributes are
 173 supported: \fBCKA_SUBJECT\fR, \fBCKA_VALUE\fR, \fBCKA_LABEL\fR, \fBCKA_ID\fR,
 174 \fBCKA_ISSUER\fR, \fBCKA_SERIAL_NUMBER\fR, and \fBCKA_CERTIFICATE_TYPE\fR.
 175 .RE
 176
 177 .sp
 178 .ne 2
 179 .na
 180 \fB\fBCKC_X_509_ATTR_CERT\fR\fR
 181 .ad
 182 .RS 23n
 183 For \fBCKC_X_509_ATTR_CERT\fR certificate objects, the following attributes are
 184 supported: \fBCKA_OWNER\fR, \fBCKA_VALUE, CKA_LABEL\fR,
 185 \fBCKA_SERIAL_NUMBER\fR, \fBCKA_AC_ISSUER\fR, \fBCKA_ATTR_TYPES\fR, and
 186 \fBCKA_CERTIFICATE_TYPE\fR.
 187 .RE
 188
 189 .sp
 190 .LP
 191 The search operation of objects matching the template is performed at
 192 \fBC_FindObjectsInit\fR. The matched objects are cached for subsequent
 193 \fBC_FindObjects\fR operations.
 194 .sp
 195 .LP
 196 The \fBpkcs11_softtoken.so\fR object provides a filesystem-based persistent
 197 token object store for storing token objects. The default location of the token
 198 object store is the user's home directory returned by \fBgetpwuid_r()\fR. The
 199 user can override the default location by using the \fB${SOFTTOKEN_DIR}\fR
 200 environment variable.
 201 .sp
 202 .LP
 203 If the token object store has never been initialized, the \fBC_Login()\fR
 204 function might return \fBCKR_OK\fR but the user will not be able to create,
 205 generate, derive or find any private token object and receives
 206 \fBCKR_PIN_EXPIRED\fR.
 207 .sp
 208 .LP
 209 The user must use the \fBpktool\fR(1) \fBsetpin\fR command with the default
 210 passphrase "changeme" as the old passphrase to change the passphrase of the
 211 object store. This action is needed to initialize and set the passphrase to a
 212 newly created token object store.
 213 .sp
 214 .LP
 215 After logging into object store with the new passphrase that was set by the
 216 \fBpktool setpin\fR command, the user can create and store the private token
 217 object in this newly created object store. Until the token object store is
 218 initialized by \fBsetpin\fR, the \fBC_Login()\fR function is allowed, but all
 219 attempts by the user to create, generate, derive or find any private token
 220 object fails with a \fBCKR_PIN_EXPIRED\fR error.
 221 .sp
 222 .LP
 223 The PIN provided for \fBC_Login()\fR and \fBC_SetPIN()\fR functions can be any
 224 string of characters with lengths between 1 and 256 and no embedded nulls.
 225 .SH RETURN VALUES
 226 .sp
 227 .LP
 228 The return values for each of the implemented functions are defined and listed
 229 in the RSA PKCS#11 v2.20 specification. See http://www.rsasecurity.com
 230 .SH FILES
 231 .sp
 232 .ne 2
 233 .na
 234 \fB\fB\fIuser_home_directory\fR/.sunw/pkcs11_softtoken\fR\fR
 235 .ad
 236 .sp .6
 237 .RS 4n
 238 user's default token object store
 239 .RE
 240
 241 .sp
 242 .ne 2
 243 .na
 244 \fB\fB${SOFTTOKEN_DIR}/pkcs11_softtoken\fR\fR
 245 .ad
 246 .sp .6
 247 .RS 4n
 248 alternate token object store
 249 .RE
 250
 251 .SH ATTRIBUTES
 252 .sp
 253 .LP
 254 See \fBattributes\fR(5) for a description of the following attributes:
 255 .sp
 256
 257 .sp
 258 .TS
 259 box;
 260 c | c
 261 l | l .
 262 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 263 _
 264 Interface Stability     Committed
 265 _
 266 MT-Level        T{
 267 MT-Safe with exceptions. See section 6.5.2 of RSA PKCS#11 v2.20.
 268 T}
 269 _
 270 Standard        PKCS#11 v2.20
 271 .TE
 272
 273 .SH SEE ALSO
 274 .sp
 275 .LP
 276 \fBpktool\fR(1), \fBcryptoadm\fR(8), \fBlibpkcs11\fR(3LIB),
 277 \fBattributes\fR(5), \fBpkcs11_kernel\fR(5)
 278 .sp
 279 .LP
 280 RSA PKCS#11 v2.20 http://www.rsasecurity.com