| blob | 5309ed33e0764ac48b7351eb4f8df9aa06405f63 |
1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All rights reserved.
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH LIBPKCS11 3LIB "Aug 4, 2008"
7 .SH NAME
8 libpkcs11 \- PKCS#11 Cryptographic Framework library
9 .SH SYNOPSIS
10 .LP
11 .nf
12 cc [ \fIflag\fR... ] \fIfile\fR... \fB-lpkcs11\fR [ \fIlibrary\fR... ]
13 #include <\fBsecurity/cryptoki.h\fR>
14 #include <\fBsecurity/pkcs11.h\fR>
15 .fi
17 .SH DESCRIPTION
18 .sp
19 .LP
20 The \fBlibpkcs11\fR library implements the RSA Security Inc. PKCS#11
21 Cryptographic Token Interface (Cryptoki), v2.20 specification by using plug-ins
22 to provide the slots.
23 .sp
24 .LP
25 Each plug-in, which also implements RSA PKCS#11 v2.20, represents one or more
26 slots.
27 .sp
28 .LP
29 The \fBlibpkcs11\fR library provides a special slot called the meta slot. The
30 meta slot provides a virtual union of capabilities of all other slots. When
31 available, the meta slot is always the first slot provided by \fBlibpkcs11\fR.
32 .sp
33 .LP
34 The meta slot feature can be configured either system-wide or by individual
35 users. System-wide configuration for meta slot features is done with the
36 \fBcryptoadm\fR(1M) utility. User configuration for meta slot features is
37 performed with environment variables.
38 .sp
39 .LP
40 By default, the following is the system-wide configuration for meta slot. Meta
41 slot is enabled. Meta slot provides token-based object support with the
42 Software RSA PKCS#11 softtoken (\fBpkcs11_softtoken\fR(5)). Meta slot is
43 allowed to move sensitive token objects to other slots if that is necessary to
44 perform an operation.
45 .sp
46 .LP
47 Users can overwrite one or more system-wide configuration options for meta slot
48 using these environment variables.
49 .sp
50 .LP
51 The \fB${METASLOT_OBJECTSTORE_SLOT}\fR and \fB${METASLOT_OBJECTSTORE_TOKEN}\fR
52 environment variables are used to specify an alternate token object store. A
53 user can specify either slot-description in \fB${METASLOT_OBJECTSTORE_SLOT}\fR
54 or token-label in \fB${METASLOT_OBJECTSTORE_TOKEN}\fR, or both. Valid values
55 for slot-description and token-label are available from output of the command:
56 .sp
57 .in +2
58 .nf
59 cryptoadm list -v
60 .fi
61 .in -2
62 .sp
64 .sp
65 .LP
66 The \fB${METASLOT_ENABLED}\fR environment variable is used to specify whether
67 the user wants to turn the metaslot feature on or off. Only two values are
68 recognized. The value "true" means meta slot will be on. The value "false"
69 means meta slot will be off.
70 .sp
71 .LP
72 The \fB${METASLOT_AUTO_KEY_MIGRATE}\fR environment variable is used to specify
73 whether the user wants sensitive token objects to move to other slots for
74 cryptographic operations. Only two values are recognized. The value "true"
75 means meta slot will migrate sensitive token objects to other slots if
76 necessary. The value "false" means meta slot will not migrate sensitive token
77 objects to other slots even if it is necessary.
78 .sp
79 .LP
80 When the meta slot feature is enabled, the slot that provides token-based
81 object support is not shown as one of the available slots. All of its
82 functionality can be used with the meta slot.
83 .sp
84 .LP
85 This library filters the list of mechanisms available from plug-ins based on
86 the policy set by \fBcryptoadm\fR(1M).
87 .sp
88 .LP
89 This library provides entry points for all PKCS#11 v2.20 functions. See the RSA
90 PKCS#11 v2.20 specification at http://www.rsasecurity.com.
91 .sp
92 .LP
93 Plug-ins are added to \fBlibpkcs11\fR by the \fBpkcs11conf\fR class action
94 script during execution of \fBpkgadd\fR(1M). The available mechanisms are
95 administered by the \fBcryptoadm\fR(1M) utility.
96 .sp
97 .LP
98 Plug-ins must have all of their library dependancies specified, including
99 \fBlibc\fR(3LIB). Libraries that have unresolved symbols, including those from
100 \fBlibc\fR, will be rejected and a message will be sent to \fBsyslog\fR(3C) for
101 such plug-ins.
102 .sp
103 .LP
104 Due to U.S. Export regulations, all plug-ins are required to be
105 cryptographically signed using the \fBelfsign\fR utility.
106 .sp
107 .LP
108 Any plug-in that is not signed or is not a compatible version of PKCS#11 will
109 be dropped by \fBlibpkcs11\fR. When a plug-in is dropped, the administrator is
110 alerted by the \fBsyslog\fR(3C) utility.
111 .sp
112 .LP
113 The <\fBsecurity/pkcs11f.h\fR> header contains function definitions. The
114 <\fBsecurity/pkcs11t.h\fR> header contains type definitions. Applications can
115 include either of these headers in place of <\fBsecurity/pkcs11.h\fR>, which
116 contains both function and type definitions.
117 .SH INTERFACES
118 .sp
119 .LP
120 The shared object \fBlibpkcs11.so.1\fR provides the public interfaces defined
121 below. See \fBIntro\fR(3) for additional information on shared object
122 interfaces.
123 .SS "PKCS#11 Standard"
124 .sp
126 .sp
127 .TS
128 l l
129 l l .
130 \fBC_CloseAllSessions\fR \fBC_CloseSession\fR
131 \fBC_CopyObject\fR \fBC_CreateObject\fR
132 \fBC_Decrypt\fR \fBC_DecryptDigestUpdate\fR
133 \fBC_DecryptFinal\fR \fBC_DecryptInit\fR
134 \fBC_DecryptUpdate\fR \fBC_DecryptVerifyUpdate\fR
135 \fBC_DeriveKey\fR \fBC_DestroyObject\fR
136 \fBC_Digest\fR \fBC_DigestEncryptUpdate\fR
137 \fBC_DigestFinal\fR \fBC_DigestInit\fR
138 \fBC_DigestKey\fR \fBC_DigestUpdate\fR
139 \fBC_Encrypt\fR \fBC_EncryptFinal\fR
140 \fBC_EncryptInit\fR \fBC_EncryptUpdate\fR
141 \fBC_Finalize\fR \fBC_FindObjects\fR
142 \fBC_FindObjectsFinal\fR \fBC_FindObjectsInit\fR
143 \fBC_GenerateKey\fR \fBC_GenerateKeyPair\fR
144 \fBC_GenerateRandom\fR \fBC_GetAttributeValue\fR
145 \fBC_GetFunctionList\fR \fBC_GetInfo\fR
146 \fBC_GetMechanismInfo\fR \fBC_GetMechanismList\fR
147 \fBC_GetObjectSize\fR \fBC_GetOperationState\fR
148 \fBC_GetSessionInfo\fR \fBC_GetSlotInfo\fR
149 \fBC_GetSlotList\fR \fBC_GetTokenInfo\fR
150 \fBC_InitPIN\fR \fBC_InitToken\fR
151 \fBC_Initialize\fR \fBC_Login\fR
152 \fBC_Logout\fR \fBC_OpenSession\fR
153 \fBC_SeedRandom\fR \fBC_SetAttributeValue\fR
154 \fBC_SetOperationState\fR \fBC_SetPIN\fR
155 \fBC_Sign\fR \fBC_SignEncryptUpdate\fR
156 \fBC_SignFinal\fR \fBC_SignInit\fR
157 \fBC_SignRecover\fR \fBC_SignRecoverInit\fR
158 \fBC_SignUpdate\fR \fBC_UnwrapKey\fR
159 \fBC_Verify\fR \fBC_VerifyFinal\fR
160 \fBC_VerifyInit\fR \fBC_VerifyRecover\fR
161 \fBC_VerifyRecoverInit\fR \fBC_VerifyUpdate\fR
162 \fBC_WaitForSlotEvent\fR \fBC_WrapKey\fR
163 .TE
165 .SS "SUNW Extensions"
166 .sp
168 .sp
169 .TS
170 l l .
171 \fBSUNW_C_GetMechSession\fR \fBSUNW_C_KeyToObject\fR
172 .TE
174 .SH FILES
175 .sp
176 .ne 2
177 .na
178 \fB\fB/usr/lib/libpkcs11.so.1\fR\fR
179 .ad
180 .RS 30n
181 shared object
182 .RE
184 .sp
185 .ne 2
186 .na
187 \fB\fB/usr/lib/64/libpkcs11.so.1\fR\fR
188 .ad
189 .RS 30n
190 64-bit shared object
191 .RE
193 .SH ATTRIBUTES
194 .sp
195 .LP
196 See \fBattributes\fR(5) for descriptions of the following attributes:
197 .sp
199 .sp
200 .TS
201 box;
202 c | c
203 l | l .
204 ATTRIBUTE TYPE ATTRIBUTE VALUE
205 Interface Stability Committed
206 _
207 MT-Level See below.
208 _
209 Standard See below.
210 .TE
212 .sp
213 .LP
214 The SUNW Extension functions are MT-Safe. The PKCS#11 Standard functions are
215 MT-Safe with exceptions. See Section 6.5.2 of RSA PKCS#11 v2.20.
216 .sp
217 .LP
218 The PKCS#11 Standard functions conform to PKCS#11 v2.20.
219 .SH SEE ALSO
220 .sp
221 .LP
222 \fBcryptoadm\fR(1M), \fBpkgadd\fR(1M), \fBIntro\fR(3),
223 \fBSUNW_C_GetMechSession\fR(3EXT), \fBsyslog\fR(3C), \fBattributes\fR(5) ,
224 \fBpkcs11_kernel\fR(5), \fBpkcs11_softtoken\fR(5)
225 .sp
226 .LP
227 RSA PKCS#11 v2.20 http://www.rsasecurity.com
228 .SH NOTES
229 .sp
230 .LP
231 If an application calls \fBC_WaitForSlotEvent()\fR without the
232 \fBCKF_DONT_BLOCK\fR flag set, \fBlibpkcs11\fR must create threads internally.
233 If, however, \fBCKF_LIBRARY_CANT_CREATE_OS_THREADS\fR is set,
234 \fBC_WaitForSlotEvent()\fR returns \fBCKR_FUNCTION_FAILED\fR.
235 .sp
236 .LP
237 The PKCS#11 library does not work with Netscape 4.\fIx\fR but does work with
238 more recent versions of Netscape and Mozilla.
239 .sp
240 .LP
241 Because \fBC_Initalize()\fR might have been called by both an application and a
242 library, it is not safe for a library or its plugins to call
243 \fBC_Finalize()\fR. A library can be finished calling functions from
244 \fBlibpkcs11\fR, while an application might not.