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