LIBPKCS11(3LIB) Interface Libraries LIBPKCS11(3LIB)

NAME


libpkcs11 - PKCS#11 Cryptographic Framework library

SYNOPSIS


PKCS#11 Cryptographic Framework Library (libpkcs11, -lpkcs11)
#include <security/cryptoki.h>
#include <security/pkcs11.h>

DESCRIPTION


The libpkcs11 library implements the RSA Security Inc. PKCS#11
Cryptographic Token Interface (Cryptoki), v2.40 specification by using
plug-ins to provide the slots.

Each plug-in, which also implements RSA PKCS#11 v2.40, represents one or
more slots.

The libpkcs11 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
libpkcs11.

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
cryptoadm(1M) utility. User configuration for meta slot features is
performed with environment variables.

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 (pkcs11_softtoken(5)). Meta slot is
allowed to move sensitive token objects to other slots if that is necessary
to perform an operation.

Users can overwrite one or more system-wide configuration options for meta
slot using these environment variables.

The ${METASLOT_OBJECTSTORE_SLOT} and ${METASLOT_OBJECTSTORE_TOKEN}
environment variables are used to specify an alternate token object store.
A user can specify either slot-description in ${METASLOT_OBJECTSTORE_SLOT}
or token-label in ${METASLOT_OBJECTSTORE_TOKEN}, or both. Valid values for
slot-description and token-label are available from output of the command:

# cryptoadm list -v

The ${METASLOT_ENABLED} 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.

The ${METASLOT_AUTO_KEY_MIGRATE} 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.

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.

This library filters the list of mechanisms available from plug-ins based
on the policy set by cryptoadm(1M).

This library provides entry points for all PKCS#11 v2.40 functions. See
the PKCS#11 v2.40 specifications at http://www.oasis-open.org.

Plug-ins are added to libpkcs11 by the pkcs11conf class action script
during execution of pkgadd(1M). The available mechanisms are administered
by the cryptoadm(1M) utility.

Plug-ins must have all of their library dependancies specified, including
libc(3LIB). Libraries that have unresolved symbols, including those from
libc(3LIB), will be rejected and a message will be sent to syslog(3C) for
such plug-ins.

Due to U.S. Export regulations, all plug-ins are required to be
cryptographically signed using the elfsign(1) utility.

Any plug-in that is not signed or is not a compatible version of PKCS#11
will be dropped by libpkcs11. When a plug-in is dropped, the administrator
is alerted by the syslog(3C) utility.

The <security/pkcs11f.h> header contains function definitions. The
<security/pkcs11t.h> header contains type definitions. Applications can
include either of these headers in place of <security/pkcs11.h>, which
contains both function and type definitions.

INTERFACES


The shared object libpkcs11.so.1 provides the public interfaces defined
below. See Intro(3) for additional information on shared object
interfaces.

PKCS#11 Standard
C_CloseAllSessions C_CloseSession
C_CopyObject C_CreateObject
C_Decrypt C_DecryptDigestUpdate
C_DecryptFinal C_DecryptInit
C_DecryptUpdate C_DecryptVerifyUpdate
C_DeriveKey C_DestroyObject
C_Digest C_DigestEncryptUpdate
C_DigestFinal C_DigestInit
C_DigestKey C_DigestUpdate
C_Encrypt C_EncryptFinal
C_EncryptInit C_EncryptUpdate
C_Finalize C_FindObjects
C_FindObjectsFinal C_FindObjectsInit
C_GenerateKey C_GenerateKeyPair
C_GenerateRandom C_GetAttributeValue
C_GetFunctionList C_GetInfo
C_GetMechanismInfo C_GetMechanismList
C_GetObjectSize C_GetOperationState
C_GetSessionInfo C_GetSlotInfo
C_GetSlotList C_GetTokenInfo
C_InitPIN C_InitToken
C_Initialize C_Login
C_Logout C_OpenSession
C_SeedRandom C_SetAttributeValue
C_SetOperationState C_SetPIN
C_Sign C_SignEncryptUpdate
C_SignFinal C_SignInit
C_SignRecover C_SignRecoverInit
C_SignUpdate C_UnwrapKey
C_Verify C_VerifyFinal
C_VerifyInit C_VerifyRecover
C_VerifyRecoverInit C_VerifyUpdate
C_WaitForSlotEvent C_WrapKey

SUNW Extensions


SUNW_C_GetMechSession SUNW_C_KeyToObject

FILES


/usr/lib/libpkcs11.so.1 shared object
/usr/lib/64/libpkcs11.so.1 64-bit shared object

ATTRIBUTES


See attributes(5) for descriptions of the following attributes:

INTERFACE STABILITY


Committed

MT-LEVEL
The SUNW Extension functions are MT-Safe. The PKCS#11 Standard functions
are MT-Safe with exceptions. See Section 2.5.3 of PKCS#11 Cryptographic
Token Usage Guide v2.40 and Section 5.1.5 of PKCS#11 Cryptographic Token
Interface Base Standard v2.40

STANDARD


The PKCS#11 Standard functions conform to PKCS#11 Cryptographic Token
Interface Profiles v2.40 Extended Provider.

SEE ALSO


cryptoadm(1M), pkgadd(1M), Intro(3), syslog(3C),
SUNW_C_GetMechSession(3EXT), attributes(5), pkcs11_kernel(5),
pkcs11_softtoken(5)

PKCS#11 Cryptographic Token Interface Base Specification v2.40 Plus Errata
01,
http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/errata01/os/pkcs11-base-v2.40-errata01-os.html.

PKCS#11 Cryptographic Token Interface Profiles v2.40,
http://docs.oasis-open.org/pkcs11/pkcs11-profiles/v2.40/pkcs11-profiles-v2.40.html.

PKCS#11 Cryptographic Token Interface Usage Guide v2.40,
http://docs.oasis-open.org/pkcs11/pkcs11-ug/v2.40/pkcs11-ug-v2.40.html.

NOTES


If an application calls C_WaitForSlotEvent() without the CKF_DONT_BLOCK
flag set, libpkcs11 must create threads internally. If, however,
CKF_LIBRARY_CANT_CREATE_OS_THREADS is set, C_WaitForSlotEvent() returns
CKR_FUNCTION_FAILED.

The PKCS#11 library does not work with Netscape 4.x but does work with more
recent versions of Netscape and Mozilla.

Because C_Initalize() might have been called by both an application and a
library, it is not safe for a library or its plugins to call C_Finalize().
A library can be finished calling functions from libpkcs11, while an
application might not.

illumos October 19, 2016 illumos