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