1 LIBPKCS11(3LIB) Interface Libraries LIBPKCS11(3LIB)
2
3 NAME
4 libpkcs11 - PKCS#11 Cryptographic Framework library
5
6 SYNOPSIS
7 PKCS#11 Cryptographic Framework Library (libpkcs11, -lpkcs11)
8 #include <security/cryptoki.h>
9 #include <security/pkcs11.h>
10
11 DESCRIPTION
12 The libpkcs11 library implements the RSA Security Inc. PKCS#11
13 Cryptographic Token Interface (Cryptoki), v2.40 specification by using
14 plug-ins to provide the slots.
15
16 Each plug-in, which also implements RSA PKCS#11 v2.40, represents one or
17 more slots.
18
19 The libpkcs11 library provides a special slot called the meta slot. The
20 meta slot provides a virtual union of capabilities of all other slots.
21 When available, the meta slot is always the first slot provided by
22 libpkcs11.
23
24 The meta slot feature can be configured either system-wide or by
25 individual users. System-wide configuration for meta slot features is
26 done with the cryptoadm(1M) utility. User configuration for meta slot
27 features is performed with environment variables.
28
29 By default, the following is the system-wide configuration for meta slot.
30 Meta slot is enabled. Meta slot provides token-based object support with
31 the Software RSA PKCS#11 softtoken (pkcs11_softtoken(5)). Meta slot is
32 allowed to move sensitive token objects to other slots if that is
33 necessary to perform an operation.
34
35 Users can overwrite one or more system-wide configuration options for
36 meta slot using these environment variables.
37
38 The ${METASLOT_OBJECTSTORE_SLOT} and ${METASLOT_OBJECTSTORE_TOKEN}
39 environment variables are used to specify an alternate token object
40 store. A user can specify either slot-description in
41 ${METASLOT_OBJECTSTORE_SLOT} or token-label in
42 ${METASLOT_OBJECTSTORE_TOKEN}, or both. Valid values for slot-
43 description and token-label are available from output of the command:
44
45 # cryptoadm list -v
46
47 The ${METASLOT_ENABLED} environment variable is used to specify whether
48 the user wants to turn the metaslot feature on or off. Only two values
49 are recognized. The value "true" means meta slot will be on. The value
50 "false" means meta slot will be off.
51
52 The ${METASLOT_AUTO_KEY_MIGRATE} environment variable is used to specify
53 whether the user wants sensitive token objects to move to other slots for
54 cryptographic operations. Only two values are recognized. The value
55 "true" means meta slot will migrate sensitive token objects to other
56 slots if necessary. The value "false" means meta slot will not migrate
57 sensitive token objects to other slots even if it is necessary.
58
59 When the meta slot feature is enabled, the slot that provides token-based
60 object support is not shown as one of the available slots. All of its
61 functionality can be used with the meta slot.
62
63 This library filters the list of mechanisms available from plug-ins based
64 on the policy set by cryptoadm(1M).
65
66 This library provides entry points for all PKCS#11 v2.40 functions. See
67 the PKCS#11 v2.40 specifications at http://www.oasis-open.org.
68
69 Plug-ins are added to libpkcs11 by the pkcs11conf class action script
70 during execution of pkgadd(1M). The available mechanisms are
71 administered by the cryptoadm(1M) utility.
72
73 Plug-ins must have all of their library dependencies specified, including
74 libc(3LIB). Libraries that have unresolved symbols, including those from
75 libc(3LIB), will be rejected and a message will be sent to syslog(3C) for
76 such plug-ins.
77
78 Due to U.S. Export regulations, all plug-ins are required to be
79 cryptographically signed using the elfsign(1) utility.
80
81 Any plug-in that is not signed or is not a compatible version of PKCS#11
82 will be dropped by libpkcs11. When a plug-in is dropped, the
83 administrator is alerted by the syslog(3C) utility.
84
85 The <security/pkcs11f.h> header contains function definitions. The
86 <security/pkcs11t.h> header contains type definitions. Applications can
87 include either of these headers in place of <security/pkcs11.h>, which
88 contains both function and type definitions.
89
90 INTERFACES
91 The shared object libpkcs11.so.1 provides the public interfaces defined
92 below. See Intro(3) for additional information on shared object
93 interfaces.
94
95 PKCS#11 Standard
96 C_CloseAllSessions C_CloseSession
97 C_CopyObject C_CreateObject
98 C_Decrypt C_DecryptDigestUpdate
99 C_DecryptFinal C_DecryptInit
100 C_DecryptUpdate C_DecryptVerifyUpdate
101 C_DeriveKey C_DestroyObject
102 C_Digest C_DigestEncryptUpdate
103 C_DigestFinal C_DigestInit
104 C_DigestKey C_DigestUpdate
105 C_Encrypt C_EncryptFinal
106 C_EncryptInit C_EncryptUpdate
107 C_Finalize C_FindObjects
108 C_FindObjectsFinal C_FindObjectsInit
109 C_GenerateKey C_GenerateKeyPair
110 C_GenerateRandom C_GetAttributeValue
111 C_GetFunctionList C_GetInfo
112 C_GetMechanismInfo C_GetMechanismList
113 C_GetObjectSize C_GetOperationState
114 C_GetSessionInfo C_GetSlotInfo
115 C_GetSlotList C_GetTokenInfo
116 C_InitPIN C_InitToken
117 C_Initialize C_Login
118 C_Logout C_OpenSession
119 C_SeedRandom C_SetAttributeValue
120 C_SetOperationState C_SetPIN
121 C_Sign C_SignEncryptUpdate
122 C_SignFinal C_SignInit
123 C_SignRecover C_SignRecoverInit
124 C_SignUpdate C_UnwrapKey
125 C_Verify C_VerifyFinal
126 C_VerifyInit C_VerifyRecover
127 C_VerifyRecoverInit C_VerifyUpdate
128 C_WaitForSlotEvent C_WrapKey
129
130 SUNW Extensions
131 SUNW_C_GetMechSession SUNW_C_KeyToObject
132
133 FILES
134 /usr/lib/libpkcs11.so.1 shared object
135 /usr/lib/64/libpkcs11.so.1 64-bit shared object
136
137 ATTRIBUTES
138 See attributes(5) for descriptions of the following attributes:
139
140 INTERFACE STABILITY
141 Committed
142
143 MT-LEVEL
144 The SUNW Extension functions are MT-Safe. The PKCS#11 Standard functions
145 are MT-Safe with exceptions. See Section 2.5.3 of PKCS#11 Cryptographic
146 Token Usage Guide v2.40 and Section 5.1.5 of PKCS#11 Cryptographic Token
147 Interface Base Standard v2.40
148
149 SEE ALSO
150 cryptoadm(1M), pkgadd(1M), Intro(3), syslog(3C),
151 SUNW_C_GetMechSession(3EXT), attributes(5), pkcs11_kernel(5),
152 pkcs11_softtoken(5)
153
154 PKCS#11 Cryptographic Token Interface Base Specification v2.40 Plus
155 Errata 01,
156 http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/errata01/os/pkcs11-base-v2.40-errata01-os.html.
157
158 PKCS#11 Cryptographic Token Interface Profiles v2.40,
159 http://docs.oasis-open.org/pkcs11/pkcs11-profiles/v2.40/pkcs11-profiles-v2.40.html.
160
161 PKCS#11 Cryptographic Token Interface Usage Guide v2.40,
162 http://docs.oasis-open.org/pkcs11/pkcs11-ug/v2.40/pkcs11-ug-v2.40.html.
163
164 STANDARDS
165 The PKCS#11 Standard functions conform to PKCS#11 Cryptographic Token
166 Interface Profiles v2.40 Extended Provider.
167
168 NOTES
169 If an application calls C_WaitForSlotEvent() without the CKF_DONT_BLOCK
170 flag set, libpkcs11 must create threads internally. If, however,
171 CKF_LIBRARY_CANT_CREATE_OS_THREADS is set, C_WaitForSlotEvent() returns
172 CKR_FUNCTION_FAILED.
173
174 Because C_Initialize() might have been called by both an application and
175 a library, it is not safe for a library or its plugins to call
176 C_Finalize(). A library can be finished calling functions from
177 libpkcs11, while an application might not.
178
179 illumos August 27, 2019 illumos