'\" te .\" Copyright (c) 2010, 2015, Oracle and/or its affiliates. All rights reserved. .TH libpkcs11 3LIB "16 Jun 2015" "SunOS 5.11" "Interface Libraries" .SH NAME libpkcs11 \- PKCS#11 Cryptographic Framework library .SH SYNOPSIS .LP .nf cc [ \fIflag\fR... ] \fIfile\fR... \fB-lpkcs11\fR [ \fIlibrary\fR... ] #include <\fBsecurity/cryptoki.h\fR> #include <\fBsecurity/pkcs11.h\fR> .fi .SH DESCRIPTION .sp .LP The \fBlibpkcs11\fR library implements the RSA Security Inc. PKCS#11 Cryptographic Token Interface (Cryptoki), v2.20 specification by using plug-ins to provide the slots. .sp .LP Each plug-in, which also implements RSA PKCS#11 v2.20, represents one or more slots. .sp .LP The \fBlibpkcs11\fR library provides a special slot called the meta slot. The meta slot provides a virtual union of capabilities of all other slots. When available, the meta slot is always the first slot provided by \fBlibpkcs11\fR. The order of the rest of the slots is not guaranteed and may vary with every load of this library. .sp .LP The meta slot feature can be configured either system-wide or by individual users. System-wide configuration for meta slot features is done with the \fBcryptoadm\fR(1M) utility. User configuration for meta slot features is performed with environment variables. .sp .LP By default, the following is the system-wide configuration for meta slot. Meta slot is enabled. Meta slot provides token-based object support with the Software RSA PKCS#11 softtoken (\fBpkcs11_softtoken\fR(5)). Meta slot is allowed to move sensitive token objects to other slots if that is necessary to perform an operation. .sp .LP Users can overwrite one or more system-wide configuration options for meta slot using these environment variables. .sp .LP The \fB${METASLOT_OBJECTSTORE_SLOT}\fR and \fB${METASLOT_OBJECTSTORE_TOKEN}\fR environment variables are used to specify an alternate token object store. A user can specify either slot-description in \fB${METASLOT_OBJECTSTORE_SLOT}\fR or token-label in \fB${METASLOT_OBJECTSTORE_TOKEN}\fR, or both. Valid values for slot-description and token-label are available from output of the command: .sp .in +2 .nf cryptoadm list -v .fi .in -2 .sp .sp .LP The \fB${METASLOT_ENABLED}\fR environment variable is used to specify whether the user wants to turn the metaslot feature on or off. Only two values are recognized. The value "true" means meta slot will be on. The value "false" means meta slot will be off. .sp .LP The \fB${METASLOT_AUTO_KEY_MIGRATE}\fR environment variable is used to specify whether the user wants sensitive token objects to move to other slots for cryptographic operations. Only two values are recognized. The value "true" means meta slot will migrate sensitive token objects to other slots if necessary. The value "false" means meta slot will not migrate sensitive token objects to other slots even if it is necessary. .sp .LP When the meta slot feature is enabled, the slot that provides token-based object support is not shown as one of the available slots. All of its functionality can be used with the meta slot. .sp .LP This library filters the list of mechanisms available from plug-ins based on the policy set by \fBcryptoadm\fR(1M). .sp .LP This library provides entry points for all PKCS#11 v2.20 functions. See the RSA PKCS#11 v2.20 specification. .sp .LP Plug-ins are added to \fBlibpkcs11\fR by the \fBpkcs11conf\fR class action script during execution of \fBpkgadd\fR(1M). The available mechanisms are administered by the \fBcryptoadm\fR(1M) utility. .sp .LP Plug-ins must have all of their library dependancies specified, including \fBlibc\fR(3LIB). Libraries that have unresolved symbols, including those from \fBlibc\fR, will be rejected and a message will be sent to \fBsyslog\fR(3C) for such plug-ins. .sp .LP Due to U.S. Export regulations, all plug-ins are required to be cryptographically signed using the \fBelfsign\fR utility. .sp .LP Any plug-in that is not signed or is not a compatible version of PKCS#11 will be dropped by \fBlibpkcs11\fR. When a plug-in is dropped, the administrator is alerted by the \fBsyslog\fR(3C) utility. .sp .LP The \fB\fR header contains function definitions. The \fB\fR header contains type definitions. Applications can include either of these headers in place of \fB\fR, which contains both function and type definitions. .SH INTERFACES .sp .LP The shared object \fBlibpkcs11.so.1\fR provides the public interfaces defined below. See \fBIntro\fR(3) for additional information on shared object interfaces. .SS "PKCS#11 Standard" .sp .sp .TS tab(); lw(2.75i) lw(2.75i) lw(2.75i) lw(2.75i) . \fBC_CloseAllSessions\fR\fBC_CloseSession\fR \fBC_CopyObject\fR\fBC_CreateObject\fR \fBC_Decrypt\fR\fBC_DecryptDigestUpdate\fR \fBC_DecryptFinal\fR\fBC_DecryptInit\fR \fBC_DecryptUpdate\fR\fBC_DecryptVerifyUpdate\fR \fBC_DeriveKey\fR\fBC_DestroyObject\fR \fBC_Digest\fR\fBC_DigestEncryptUpdate\fR \fBC_DigestFinal\fR\fBC_DigestInit\fR \fBC_DigestKey\fR\fBC_DigestUpdate\fR \fBC_Encrypt\fR\fBC_EncryptFinal\fR \fBC_EncryptInit\fR\fBC_EncryptUpdate\fR \fBC_Finalize\fR\fBC_FindObjects\fR \fBC_FindObjectsFinal\fR\fBC_FindObjectsInit\fR \fBC_GenerateKey\fR\fBC_GenerateKeyPair\fR \fBC_GenerateRandom\fR\fBC_GetAttributeValue\fR \fBC_GetFunctionList\fR\fBC_GetInfo\fR \fBC_GetMechanismInfo\fR\fBC_GetMechanismList\fR \fBC_GetObjectSize\fR\fBC_GetOperationState\fR \fBC_GetSessionInfo\fR\fBC_GetSlotInfo\fR \fBC_GetSlotList\fR\fBC_GetTokenInfo\fR \fBC_InitPIN\fR\fBC_InitToken\fR \fBC_Initialize\fR\fBC_Login\fR \fBC_Logout\fR\fBC_OpenSession\fR \fBC_SeedRandom\fR\fBC_SetAttributeValue\fR \fBC_SetOperationState\fR\fBC_SetPIN\fR \fBC_Sign\fR\fBC_SignEncryptUpdate\fR \fBC_SignFinal\fR\fBC_SignInit\fR \fBC_SignRecover\fR\fBC_SignRecoverInit\fR \fBC_SignUpdate\fR\fBC_UnwrapKey\fR \fBC_Verify\fR\fBC_VerifyFinal\fR \fBC_VerifyInit\fR\fBC_VerifyRecover\fR \fBC_VerifyRecoverInit\fR\fBC_VerifyUpdate\fR \fBC_WaitForSlotEvent\fR\fBC_WrapKey\fR .TE .SS "SUNW Extensions" .sp .sp .TS tab(); lw(2.75i) lw(2.75i) . \fBSUNW_C_GetMechSession\fR\fBSUNW_C_KeyToObject\fR .TE .SH FILES .sp .ne 2 .mk .na \fB\fB/usr/lib/libpkcs11.so.1\fR\fR .ad .RS 30n .rt shared object .RE .sp .ne 2 .mk .na \fB\fB/usr/lib/64/libpkcs11.so.1\fR\fR .ad .RS 30n .rt 64-bit shared object .RE .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Availabilitysystem/library Interface StabilityCommitted _ MT-LevelSee below. _ StandardSee below. .TE .sp .LP The SUNW Extension functions are MT-Safe. The PKCS#11 Standard functions are MT-Safe with exceptions. See Section 6.6.2 of RSA PKCS#11 v2.20. .sp .LP The PKCS#11 Standard functions conform to PKCS#11 v2.20. .SH SEE ALSO .sp .LP \fBcryptoadm\fR(1M), \fBpkgadd\fR(1M), \fBIntro\fR(3), \fBSUNW_C_GetMechSession\fR(3EXT), \fBsyslog\fR(3C), \fBattributes\fR(5) , \fBpkcs11_kernel\fR(5), \fBpkcs11_softtoken\fR(5) .SH NOTES .sp .LP If an application calls \fBC_WaitForSlotEvent()\fR without the \fBCKF_DONT_BLOCK\fR flag set, \fBlibpkcs11\fR must create threads internally. If, however, \fBCKF_LIBRARY_CANT_CREATE_OS_THREADS\fR is set, \fBC_WaitForSlotEvent()\fR returns \fBCKR_FUNCTION_FAILED\fR. .sp .LP The PKCS#11 library does not work with Netscape 4.\fIx\fR but does work with more recent versions of Netscape and Mozilla. .sp .LP Because \fBC_Initalize()\fR might have been called by both an application and a library, it is not safe for a library or its plugins to call \fBC_Finalize()\fR. A library can be finished calling functions from \fBlibpkcs11\fR, while an application might not.