Web Services PKCS #11 library compliance with the PKCS #11 specification

Supported functions

The following sections list the PKCS #11 functions supported by the PKCS #11 library. For a list of supported mechanisms, see Mechanisms.

General purpose functions

The following functions perform as described in the PKCS #11 specification:

  • C_Finalize

  • C_GetInfo

  • C_GetFunctionList

  • C_Initialize.

Slot and token management functions

The following functions perform as described in the PKCS #11 specification:

  • C_GetSlotInfo

  • C_GetTokenInfo

  • C_GetMechanismList

  • C_GetMechanismInfo

  • C_GetSlotList.

C_GetSlotList returns a list of slot IDs. You cannot make any assumptions about the values of these handles. These handles are not equivalent to the slot numbers returned by the Web Services server.

Standard session management functions

The following functions perform as described in the PKCS #11 specification:

  • C_OpenSession

  • C_CloseSession

  • C_CloseAllSessions

  • C_Login

  • C_Logout

  • C_GetSessionInfo

Object management functions

The following functions perform as described in the PKCS #11 specification:

  • C_CreateObject

  • C_DestroyObject

  • C_GetAttributeValue

  • C_FindObjectsInit

  • C_FindObjects

  • C_FindObjectsFinal

  • C_SetAttributeValue

Encryption functions

The following functions perform as described in the PKCS #11 specification:

  • C_EncryptInit

  • C_Encrypt

Decryption functions

The following functions perform as described in the PKCS #11 specification:

  • C_DecryptInit

  • C_Decrypt

Sign functions

The following functions perform as described in the PKCS #11 specification:

  • C_SignInit

  • C_Sign

Verify functions

The following functions perform as described in the PKCS #11 specification:

  • C_VerifyInit

  • C_Verify

Key-management functions

The following function performs as described in the PKCS #11 specification:

  • C_GenerateKey

  • C_GenerateKeyPair

The Web Services PKCS #11 library does not currently support creating key objects with C_CreateObject. Use C_GenerateKey to generate a secret key object and C_GenerateKeyPair to generate a public/private key pair.

C_GenerateKey will only generate key types supported by the PKCS #11 library.

String fields such as CKA_LABEL and CKA_APPLICATION should not contain any HTML character for example <, > or & as this can result in those values becoming corrupted when they are retrieved later.

Message digesting functions

The following functions perform as described in the PKCS #11 specification:

  • C_DigestInit

  • C_Digest

  • C_DigestUpdate

  • C_DigestFinal

Random number generation function

The following function performs as described in the PKCS #11 specification:

  • C_GenerateRandom

Objects

The following table lists the objects currently supported by the PKCS #11 library.

Object Supported Types

CKO_DATA

CKO_CERTIFICATE

CKC_X_509

CKO_SECRET_KEY

CKK_AES
CKK_SHA256_HMAC
CKK_SHA384_HMAC
CKK_SHA512_HMAC

CKO_PRIVATE_KEY

CKK_RSA
CKK_EC

CKO_PUBLIC_KEY

CKK_RSA
CKK_EC

CKO_PROFILE

CKP_BASELINE_PROVIDER
The PKCS #11 provider implementation conforms to the Baseline Provider Clause defined in section 3.3 of PKCS #11 Cryptographic Token Interface Profiles Version 3.0.

Mechanisms

The following table lists the mechanisms currently supported by the PKCS #11 library and the functions available to each one.

Mechanism Encrypt & Decrypt Sign & Verify SR & VR Digest Gen. Key/Key Pair Wrap & Unwrap Derive Key

CKM_AES_CBC_PAD

Y

—

—

—

—

—

—

CKM_AES_CBC

Y

—

—

—

—

—

—

CKM_AES_GCM

Y

—

—

—

—

—

—

CKM_AES_KEY_GEN

—

—

—

—

Y

—

—

CKM_SHA256_HMAC

—

Y

—

—

—

—

—

CKM_SHA256_HMAC_GENERAL

—

Y

—

—

—

—

—

CKM_SHA384_HMAC

—

Y

—

—

—

—

—

CKM_SHA384_HMAC_GENERAL

—

Y

—

—

—

—

—

CKM_SHA512_HMAC

—

Y

—

—

—

—

—

CKM_SHA512_HMAC_GENERAL

—

Y

—

—

—

—

—

CKM_SHA256_KEY_GEN

—

—

—

—

Y

—

—

CKM_SHA384_KEY_GEN

—

—

—

—

Y

—

—

CKM_SHA512_KEY_GEN

—

—

—

—

Y

—

—

CKM_SHA_1

—

—

—

Y

—

—

—

CKM_SHA224

—

—

—

Y

—

—

—

CKM_SHA256

—

—

—

Y

—

—

—

CKM_SHA384

—

—

—

Y

—

—

—

CKM_SHA512

—

—

—

Y

—

—

—

CKM_SHA3_224

—

—

—

Y

—

—

—

CKM_SHA3_256

—

—

—

Y

—

—

—

CKM_SHA3_384

—

—

—

Y

—

—

—

CKM_SHA3_512

—

—

—

Y

—

—

—

CKM_SHA256_RSA_PKCS_PSS

—

Y

—

—

—

—

—

CKM_SHA256_RSA_PKCS

—

Y

—

—

—

—

—

CKM_SHA384_RSA_PKCS_PSS

—

Y

—

—

—

—

—

CKM_SHA384_RSA_PKCS

—

Y

—

—

—

—

—

CKM_SHA512_RSA_PKCS_PSS

—

Y

—

—

—

—

—

CKM_SHA512_RSA_PKCS

—

Y

—

—

—

—

—

CKM_RSA_PKCS_KEY_PAIR_GEN

—

—

—

—

Y

—

—

CKM_RSA_PKCS_OAEP

Y

—

—

—

—

—

—

CKM_RSA_PKCS

Y

—

—

—

—

—

—

CKM_ECDSA_KEY_PAIR_GEN

—

—

—

—

Y

—

—

CKM_ECDSA_SHA256

—

Y

—

—

—

—

—

CKM_ECDSA_SHA384

—

Y

—

—

—

—

—

CKM_ECDSA_SHA512

—

Y

—

—

—

—

—

In this table:

  • Y indicates that the function is supported by the mechanism.

  • — indicates that the function is not supported by the mechanism.

Notes on Mechanisms

AES Mechanisms

The AES mechanisms support three different key sizes: 16, 24, and 32 bytes. For non-padded AES mechanisms the plaintext size must be a multiple of the block size (16 bytes).

For CKM_AES_GCM, the following restrictions apply to the CKM_GCM_PARAMS structure:

  • ulIvLen must be 12 bytes.

  • ulTagBits must be 128 bits.

CKM_AES_GCM is not supported with Security Worlds conforming to FIPS 140 Level 3.

HMAC Mechanisms

HMAC_GENERAL mechanisms support signature lengths ranging from half the output size to the full output size. For example CKM_SHA256_HMAC_GENERAL supports outputs in the range 16-32 bytes.

RSA Mechanisms

For the CKM_RSA_PKCS_OAEP mechanism the hashAlg and the mgf values specified by CK_RSA_PKCS_OAEP_PARAMS must have the same SHA hash size. The supported pairs of values are as follows:

hashAlg mgf

CKM_SHA_1

CKG_MGF1_SHA1

CKM_SHA256

CKG_MGF1_SHA256

CKM_SHA384

CKG_MGF1_SHA384

CKM_SHA512

CKG_MGF1_SHA512

For a hash length h and RSA modulus length k in bytes, the longest message that can be encrypted is k-2h-2 bytes long.

For CKM_SHA*_RSA_PKCS_PSS mechanisms the hashAlg and the mgf values specified by CK_RSA_PKCS_PSS_PARAMS must have the same SHA hash size.The sLen value is expected to be the length of the message hash in bytes.

The supported sets of values for hashAlg, mgf and sLen are as follows:

hashAlg mgf sLen

CKM_SHA256

CKG_MGF1_SHA256

32

CKM_SHA384

CKG_MGF1_SHA384

48

CKM_SHA512

CKG_MGF1_SHA512

64

ECDSA Mechanisms

For ECDSA mechanisms, the CKA_EC_PARAMS attribute must be supplied for key generation. Its value is that of the object identifier format (oId), supplied as a byte array. Only the curves below are supported.

Curve oId

P-256

{ 0x06, 0x08, 0x2a, 0x86, 0x48, 0xce, 0x3d, 0x03, 0x01, 0x07 }

P-384

{ 0x06, 0x05, 0x2b, 0x81, 0x04, 0x00, 0x22 }

P-521

{ 0x06, 0x05, 0x2b, 0x81, 0x04, 0x00, 0x23 }

For all supported ECDSA mechanisms, the field size has a minimum of 256 bits and a maximum of 512.

For more information, including minimum and maximum key sizes, run ckmechinfo as described in Utilities in the Web Services PKCS #11 library.

Attributes

If providing these attributes when creating an object or generating a key, they must be set to CK_FALSE:

  • CKA_DERIVE

  • CKA_EXTRACTABLE

  • CKA_COPYABLE

  • CKA_TRUSTED

  • CKA_UNWRAP

  • CKA_WRAP

  • CKA_WRAP_WITH_TRUSTED

If providing these attributes when creating an object or generating a key, they must be set to CK_TRUE:

  • CKA_SENSITIVE

  • CKA_DESTROYABLE

If providing these attributes when creating an object, they must be set to CK_TRUE:

  • CKA_ALWAYS_SENSITIVE

  • CKA_NEVER_EXTRACTABLE

  • CKA_LOCAL

This attribute must be set to CK_TRUE when creating an object or generating a key:

  • CKA_TOKEN

This read-only attribute can be included in a search template provided to C_FindObjectsInit and can be retrieved using C_GetAttributeValue:

  • CKA_UNIQUE_ID

These attributes can be set using C_SetAttributeValue:

  • CKA_EXTRACTABLE (only from CK_FALSE to CK_FALSE)

  • CKA_LABEL

CKA_PUBLIC_EXPONENT value, if provided, must be an odd number greater than 2 and less than 0x7FFFFFFF and should be prime. The bit length of CKA_PUBLIC_EXPONENT must be less than half the key length. The PKCS #11 library only supports token objects, not session objects.