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 18The 19.Nm 20library implements the RSA Security Inc. PKCS#11 21Cryptographic Token Interface (Cryptoki), v2.40 specification by using plug-ins 22to provide the slots. 23.Lp 24Each plug-in, which also implements RSA PKCS#11 v2.40, represents one or more 25slots. 26.Lp 27The 28.Nm 29library provides a special slot called the meta slot. 30The meta slot provides a virtual union of capabilities of all other slots. 31When available, the meta slot is always the first slot provided by 32.Nm . 33.Lp 34The meta slot feature can be configured either system-wide or by individual 35users. 36System-wide configuration for meta slot features is done with the 37.Xr cryptoadm 1M 38utility. 39User configuration for meta slot features is performed with environment 40variables. 41.Lp 42By default, the following is the system-wide configuration for meta slot. 43Meta slot is enabled. 44Meta slot provides token-based object support with the Software RSA PKCS#11 45softtoken 46.Pq Xr pkcs11_softtoken 5 . 47Meta slot is 48allowed to move sensitive token objects to other slots if that is necessary to 49perform an operation. 50.Lp 51Users can overwrite one or more system-wide configuration options for meta slot 52using these environment variables. 53.Lp 54The 55.Ev ${METASLOT_OBJECTSTORE_SLOT} 56and 57.Ev ${METASLOT_OBJECTSTORE_TOKEN} 58environment variables are used to specify an alternate token object store. 59A user can specify either slot-description in 60.Ev ${METASLOT_OBJECTSTORE_SLOT} 61or token-label in 62.Ev ${METASLOT_OBJECTSTORE_TOKEN} , or both. 63Valid values for slot-description and token-label are available from output of 64the command: 65.Bd -literal -offset indent 66# cryptoadm list -v 67.Ed 68.Lp 69The 70.Ev ${METASLOT_ENABLED} 71environment variable is used to specify whether 72the user wants to turn the metaslot feature on or off. 73Only two values are recognized. 74The value "true" means meta slot will be on. 75The value "false" means meta slot will be off. 76.Lp 77The 78.Ev ${METASLOT_AUTO_KEY_MIGRATE} 79environment variable is used to specify 80whether the user wants sensitive token objects to move to other slots for 81cryptographic operations. 82Only two values are recognized. 83The value "true" means meta slot will migrate sensitive token objects to other 84slots if necessary. 85The value "false" means meta slot will not migrate sensitive token objects to 86other slots even if it is necessary. 87.Lp 88When the meta slot feature is enabled, the slot that provides token-based 89object support is not shown as one of the available slots. 90All of its functionality can be used with the meta slot. 91.Lp 92This library filters the list of mechanisms available from plug-ins based on 93the policy set by 94.Xr cryptoadm 1M . 95.Lp 96This library provides entry points for all PKCS#11 v2.40 functions. 97See the PKCS#11 v2.40 specifications at 98.Lk http://www.oasis-open.org. 99.Lp 100Plug-ins are added to 101.Nm 102by the 103.Sy pkcs11conf 104class action 105script during execution of 106.Xr pkgadd 1M . 107The available mechanisms are administered by the 108.Xr cryptoadm 1M 109utility. 110.Lp 111Plug-ins must have all of their library dependancies specified, including 112.Xr libc 3LIB . 113Libraries that have unresolved symbols, including those from 114.Xr libc 3LIB , 115will be rejected and a message will be sent to 116.Xr syslog 3C 117for such plug-ins. 118.Lp 119Due to U.S. Export regulations, all plug-ins are required to be 120cryptographically signed using the 121.Xr elfsign 1 122utility. 123.Lp 124Any plug-in that is not signed or is not a compatible version of PKCS#11 will 125be dropped by 126.Nm . 127When a plug-in is dropped, the administrator is alerted by the 128.Xr syslog 3C 129utility. 130.Lp 131The 132.In security/pkcs11f.h 133header contains function definitions. 134The 135.In security/pkcs11t.h 136header contains type definitions. 137Applications can include either of these headers in place of 138.In security/pkcs11.h , 139which contains both function and type definitions. 140.Sh INTERFACES 141The shared object 142.Pa libpkcs11.so.1 143provides the public interfaces defined below. 144See 145.Xr Intro 3 146for 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 194shared object 195.It Pa /usr/lib/64/libpkcs11.so.1 19664-bit shared object 197.El 198.Sh ATTRIBUTES 199See 200.Xr attributes 5 201for descriptions of the following attributes: 202.Sh INTERFACE STABILITY 203.Sy Committed 204.Sh MT-LEVEL 205The SUNW Extension functions are MT-Safe. 206The PKCS#11 Standard functions are MT-Safe with exceptions. 207See Section 2.5.3 of PKCS#11 Cryptographic Token Usage Guide v2.40 and 208Section 5.1.5 of PKCS#11 Cryptographic Token Interface Base Standard v2.40 209.Sh STANDARD 210The PKCS#11 Standard functions conform to PKCS#11 Cryptographic Token 211Interface 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 234If an application calls 235.Fn C_WaitForSlotEvent 236without the 237.Dv CKF_DONT_BLOCK 238flag set, 239.Nm 240must create threads internally. 241If, however, 242.Dv CKF_LIBRARY_CANT_CREATE_OS_THREADS 243is set, 244.Fn C_WaitForSlotEvent 245returns 246.Dv CKR_FUNCTION_FAILED . 247.Lp 248The PKCS#11 library does not work with Netscape 4.\fIx\fR but does work with 249more recent versions of Netscape and Mozilla. 250.Lp 251Because 252.Fn C_Initalize 253might have been called by both an application and a 254library, it is not safe for a library or its plugins to call 255.Fn C_Finalize . 256A library can be finished calling functions from 257.Nm , 258while an application might not. 259