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