1 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All rights reserved.
   2 .\" Copyright 2016 Jason King.
   3 .\"
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .Dd Oct 19, 2016
   8 .Dt LIBPKCS11 3LIB
   9 .Os
  10 .Sh NAME
  11 .Nm libpkcs11
  12 .Nd PKCS#11 Cryptographic Framework library
  13 .Sh SYNOPSIS
  14 .Lb libpkcs11
  15 .In security/cryptoki.h
  16 .In security/pkcs11.h
  17 .Sh DESCRIPTION
  18 The
  19 .Nm
  20 library implements the RSA Security Inc. PKCS#11
  21 Cryptographic Token Interface (Cryptoki), v2.40 specification by using plug-ins
  22 to provide the slots.
  23 .Lp
  24 Each plug-in, which also implements RSA PKCS#11 v2.40, represents one or more
  25 slots.
  26 .Lp
  27 The
  28 .Nm
  29 library provides a special slot called the meta slot.
  30 The meta slot provides a virtual union of capabilities of all other slots.
  31 When available, the meta slot is always the first slot provided by
  32 .Nm .
  33 .Lp
  34 The meta slot feature can be configured either system-wide or by individual
  35 users.
  36 System-wide configuration for meta slot features is done with the
  37 .Xr cryptoadm 1M
  38 utility.
  39 User configuration for meta slot features is performed with environment
  40 variables.
  41 .Lp
  42 By default, the following is the system-wide configuration for meta slot.
  43 Meta slot is enabled.
  44 Meta slot provides token-based object support with the Software RSA PKCS#11
  45 softtoken
  46 .Pq Xr pkcs11_softtoken 5 .
  47 Meta slot is
  48 allowed to move sensitive token objects to other slots if that is necessary to
  49 perform an operation.
  50 .Lp
  51 Users can overwrite one or more system-wide configuration options for meta slot
  52 using these environment variables.
  53 .Lp
  54 The
  55 .Ev ${METASLOT_OBJECTSTORE_SLOT}
  56 and
  57 .Ev ${METASLOT_OBJECTSTORE_TOKEN}
  58 environment variables are used to specify an alternate token object store.
  59 A user can specify either slot-description in
  60 .Ev ${METASLOT_OBJECTSTORE_SLOT}
  61 or token-label in
  62 .Ev ${METASLOT_OBJECTSTORE_TOKEN} , or both.
  63 Valid values for slot-description and token-label are available from output of
  64 the command:
  65 .Bd -literal -offset indent
  66 # cryptoadm list -v
  67 .Ed
  68 .Lp
  69 The
  70 .Ev ${METASLOT_ENABLED}
  71 environment variable is used to specify whether
  72 the user wants to turn the metaslot feature on or off.
  73 Only two values are recognized.
  74 The value "true" means meta slot will be on.
  75 The value "false" means meta slot will be off.
  76 .Lp
  77 The
  78 .Ev ${METASLOT_AUTO_KEY_MIGRATE}
  79 environment variable is used to specify
  80 whether the user wants sensitive token objects to move to other slots for
  81 cryptographic operations.
  82 Only two values are recognized.
  83 The value "true" means meta slot will migrate sensitive token objects to other
  84 slots if necessary.
  85 The value "false" means meta slot will not migrate sensitive token objects to
  86 other slots even if it is necessary.
  87 .Lp
  88 When the meta slot feature is enabled, the slot that provides token-based
  89 object support is not shown as one of the available slots.
  90 All of its functionality can be used with the meta slot.
  91 .Lp
  92 This library filters the list of mechanisms available from plug-ins based on
  93 the policy set by
  94 .Xr cryptoadm 1M .
  95 .Lp
  96 This library provides entry points for all PKCS#11 v2.40 functions.
  97 See the PKCS#11 v2.40 specifications at
  98 .Lk http://www.oasis-open.org.
  99 .Lp
 100 Plug-ins are added to
 101 .Nm
 102 by the
 103 .Sy pkcs11conf
 104 class action
 105 script during execution of
 106 .Xr pkgadd 1M .
 107 The available mechanisms are administered by the
 108 .Xr cryptoadm 1M
 109 utility.
 110 .Lp
 111 Plug-ins must have all of their library dependancies specified, including
 112 .Xr libc 3LIB .
 113 Libraries that have unresolved symbols, including those from
 114 .Xr libc 3LIB ,
 115 will be rejected and a message will be sent to
 116 .Xr syslog 3C
 117 for such plug-ins.
 118 .Lp
 119 Due to U.S. Export regulations, all plug-ins are required to be
 120 cryptographically signed using the
 121 .Xr elfsign 1
 122 utility.
 123 .Lp
 124 Any plug-in that is not signed or is not a compatible version of PKCS#11 will
 125 be dropped by
 126 .Nm .
 127 When a plug-in is dropped, the administrator is alerted by the
 128 .Xr syslog 3C
 129 utility.
 130 .Lp
 131 The
 132 .In security/pkcs11f.h
 133 header contains function definitions.
 134 The
 135 .In security/pkcs11t.h
 136 header contains type definitions.
 137 Applications can include either of these headers in place of
 138 .In security/pkcs11.h ,
 139 which contains both function and type definitions.
 140 .Sh INTERFACES
 141 The shared object
 142 .Pa libpkcs11.so.1
 143 provides the public interfaces defined below.
 144 See
 145 .Xr Intro 3
 146 for additional information on shared object interfaces.
 147 .Ss "PKCS#11 Standard"
 148 .\"
 149 .\" Use SUNW_C_GetMechSession for the first column so both sections will
 150 .\" line up better when rendered
 151 .\"
 152 .Bl -column -offset indent ".Sy SUNW_C_GetMechSession" ".Sy C_DecryptDigestUpdate"
 153 .It Sy C_CloseAllSessions Ta Sy C_CloseSession
 154 .It Sy C_CopyObject Ta Sy C_CreateObject
 155 .It Sy C_Decrypt Ta Sy C_DecryptDigestUpdate
 156 .It Sy C_DecryptFinal Ta Sy C_DecryptInit
 157 .It Sy C_DecryptUpdate Ta Sy C_DecryptVerifyUpdate
 158 .It Sy C_DeriveKey Ta Sy C_DestroyObject
 159 .It Sy C_Digest Ta Sy C_DigestEncryptUpdate
 160 .It Sy C_DigestFinal Ta Sy C_DigestInit
 161 .It Sy C_DigestKey Ta Sy C_DigestUpdate
 162 .It Sy C_Encrypt Ta Sy C_EncryptFinal
 163 .It Sy C_EncryptInit Ta Sy C_EncryptUpdate
 164 .It Sy C_Finalize Ta Sy C_FindObjects
 165 .It Sy C_FindObjectsFinal Ta Sy C_FindObjectsInit
 166 .It Sy C_GenerateKey Ta Sy C_GenerateKeyPair
 167 .It Sy C_GenerateRandom Ta Sy C_GetAttributeValue
 168 .It Sy C_GetFunctionList Ta Sy C_GetInfo
 169 .It Sy C_GetMechanismInfo Ta Sy C_GetMechanismList
 170 .It Sy C_GetObjectSize Ta Sy C_GetOperationState
 171 .It Sy C_GetSessionInfo Ta Sy C_GetSlotInfo
 172 .It Sy C_GetSlotList Ta Sy C_GetTokenInfo
 173 .It Sy C_InitPIN Ta Sy C_InitToken
 174 .It Sy C_Initialize Ta Sy C_Login
 175 .It Sy C_Logout Ta Sy C_OpenSession
 176 .It Sy C_SeedRandom Ta Sy C_SetAttributeValue
 177 .It Sy C_SetOperationState Ta Sy C_SetPIN
 178 .It Sy C_Sign Ta Sy C_SignEncryptUpdate
 179 .It Sy C_SignFinal Ta Sy C_SignInit
 180 .It Sy C_SignRecover Ta Sy C_SignRecoverInit
 181 .It Sy C_SignUpdate Ta Sy C_UnwrapKey
 182 .It Sy C_Verify Ta Sy C_VerifyFinal
 183 .It Sy C_VerifyInit Ta Sy C_VerifyRecover
 184 .It Sy C_VerifyRecoverInit Ta Sy C_VerifyUpdate
 185 .It Sy C_WaitForSlotEvent Ta Sy C_WrapKey
 186 .El
 187 .Ss "SUNW Extensions"
 188 .Bl -column -offset indent ".Sy SUNW_C_GetMechSession" ".Sy C_DecryptDigestUpdate"
 189 .It Sy SUNW_C_GetMechSession Ta Sy SUNW_C_KeyToObject
 190 .El
 191 .Sh FILES
 192 .Bl -tag -compact -width Pa
 193 .It Pa /usr/lib/libpkcs11.so.1
 194 shared object
 195 .It Pa /usr/lib/64/libpkcs11.so.1
 196 64-bit shared object
 197 .El
 198 .Sh ATTRIBUTES
 199 See
 200 .Xr attributes 5
 201 for descriptions of the following attributes:
 202 .Sh INTERFACE STABILITY
 203 .Sy Committed
 204 .Sh MT-LEVEL
 205 The SUNW Extension functions are MT-Safe.
 206 The PKCS#11 Standard functions are MT-Safe with exceptions.
 207 See Section 2.5.3 of PKCS#11 Cryptographic Token Usage Guide v2.40 and
 208 Section 5.1.5 of PKCS#11 Cryptographic Token Interface Base Standard v2.40
 209 .Sh STANDARD
 210 The PKCS#11 Standard functions conform to PKCS#11 Cryptographic Token
 211 Interface Profiles v2.40 Extended Provider.
 212 .Sh SEE ALSO
 213 .Xr cryptoadm 1M ,
 214 .Xr pkgadd 1M ,
 215 .Xr Intro 3 ,
 216 .Xr syslog 3C ,
 217 .Xr SUNW_C_GetMechSession 3EXT ,
 218 .Xr attributes 5  ,
 219 .Xr pkcs11_kernel 5 ,
 220 .Xr pkcs11_softtoken 5
 221 .Rs
 222 .%T "PKCS#11 Cryptographic Token Interface Base Specification v2.40 Plus Errata 01"
 223 .%U http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/errata01/os/pkcs11-base-v2.40-errata01-os.html
 224 .Re
 225 .Rs
 226 .%T "PKCS#11 Cryptographic Token Interface Profiles v2.40"
 227 .%U http://docs.oasis-open.org/pkcs11/pkcs11-profiles/v2.40/pkcs11-profiles-v2.40.html
 228 .Re
 229 .Rs
 230 .%T "PKCS#11 Cryptographic Token Interface Usage Guide v2.40"
 231 .%U http://docs.oasis-open.org/pkcs11/pkcs11-ug/v2.40/pkcs11-ug-v2.40.html
 232 .Re
 233 .Sh NOTES
 234 If an application calls
 235 .Fn C_WaitForSlotEvent
 236 without the
 237 .Dv CKF_DONT_BLOCK
 238 flag set,
 239 .Nm
 240 must create threads internally.
 241 If, however,
 242 .Dv CKF_LIBRARY_CANT_CREATE_OS_THREADS
 243 is set,
 244 .Fn C_WaitForSlotEvent
 245 returns
 246 .Dv CKR_FUNCTION_FAILED .
 247 .Lp
 248 The PKCS#11 library does not work with Netscape 4.\fIx\fR but does work with
 249 more recent versions of Netscape and Mozilla.
 250 .Lp
 251 Because
 252 .Fn C_Initalize
 253 might have been called by both an application and a
 254 library, it is not safe for a library or its plugins to call
 255 .Fn C_Finalize .
 256 A library can be finished calling functions from
 257 .Nm ,
 258 while an application might not.