Document toolboxDocument toolbox

Personal Desktop PKCS#11

Personal Desktop includes a PKCS#11 compliant library. By using this library, third party applications can interact with the cryptographic functions and tokens in the underlying Personal Desktop Token-API. Personal Desktop PKCS#11 is optimized for use with SSL in Mozilla-based browsers to access secure web sites.

Implemented API functions

Function

Description

Function

Description

General purpose

C_Initialize

Initializes Cryptoki.

C_Finalize

Cleans up miscellaneous Cryptoki functions.

C_GetInfo

Obtains general information about Cryptoki.

C_GetFunctionList

Obtains entry points of Cryptoki library functions.

Slot and Token Management

C_GetSlotList

Obtains a list of slots in the system.

C_GetSlotInfo

Obtains information about a particular slot.

C_GetTokenInfo

Obtains information about a particular token.

C_GetMechanismList

Obtains a list of mechanisms supported by a token.

C_GetMechanismInfo

Obtains information about a particular mechanism.

C_SetPIN

Modifies the PIN of the user that is currently logged in.

C_WaitForSlotEvent

Waits for slot event (token insertion, removal etc.) to occur.

C_UnblockPIN*

Can be used to unblock a PIN.

C_InitTokenPPA*

See "Exceptions from the PKCS#11 specification".

C_GetProperty*

See "Exceptions from the PKCS#11 specification".

C_SetSlotProperty*

See "Exceptions from the PKCS#11 specification".

Session Management

C_OpenSession

Opens a connection or “session” between an application and a particular token.

C_CloseSession

Closes a session.

C_CloseAllSessions

Closes all sessions with a token.

C_GetSessionInfo

Obtains information about the session.

C_Login

Logs into a token. Only CKU_USER is supported for soft tokens.

C_Logout

Logs out from a token.

Object Management

C_CreateObject

Creates a new object.

C_CopyObject

Copies an object, creating a new object for the copy.

C_DestroyObject

Destroys an object.

C_GetAttributeValue

Obtains an attribute value of an object.

C_SetAttributeValue

Modifies the value of one or more attributes of an object.

C_FindObjectsInit

Initializes an object search operation.

C_FindObjects

Continues an object search operation.

C_FindObjectsFinal

Finishes an object search operation.

Encryption and Decryption

C_EncryptInit

Initializes an encryption operation.

C_Encrypt

Encrypts single-part data.

C_EncryptUpdate

Continues a multiple-part encryption operation.

C_EncryptFinal

Finishes a multiple-part encryption operation.

C_DecryptInit

Initializes a decryption operation.

C_Decrypt

Decrypts single-part encrypted data.

C_DecryptUpdate

Continues a multiple-part decryption operation.

C_DecryptFinal

Finishes a multiple-part decryption operation.

Message Digesting

C_DigestInit

Initializes a message-digesting operation.

C_Digest

Digests data in a single part.

C_DigestUpdate

Continues a multiple-part digesting operation.

C_DigestFinal

Finishes a multiple-part digesting operation.

Signing and Verifying

C_SignInit

Initializes a signature operation.

C_Sign

Signs single part data.

C_SignUpdate

Continues a multiple-part signing operation.

C_SignFinal

Finishes a multiple-part signing operation.

C_SignRecoverInit

Initializes a signature operation, where the data can be recovered from the signature.

C_SignRecover

Signs single-part data, where the data can be recovered from the signature.

C_VerifyInit

Initializes a verification operation.

C_Verify

Verifies a signature on single-part data.

C_VerifyRecoverInit

Initializes a verification operation where the data is recovered from the signature.

C_VerifyRecover

Verifies single-part data, where the data can be recovered from the signature.

Key Management

C_GenerateKeyPair

Generates a public/private key pair, creating new key objects.

C_WrapKey

Wraps (that is, encrypts) a key.

C_UnwrapKey

Unwraps (that is, decrypts) a wrapped key, creating a new private key or secret key object.

Random Number Generation

C_SeedRandom

Mixes additional seed material into the token’s random number generator.

C_GenerateRandom

Generates random or pseudo-random data.

*This function is not a member of the PKCS#11 v2.20 specification.

Exceptions from the PKCS#11 specification

The PKCS#11 v2.20 specification is the complete documentation of the API implemented by Personal Desktop PKCS#11. This section describes exceptions from the PKCS#11 specification.

Function

Exception

Function

Exception

C_GetSlotList

Each physical smart card token will, by default, be shown as two virtual tokens to allow multiple PIN codes on a smart card. If only one PIN is available, then the second slot will be empty.

C_Login

Only CKU_USER is supported for software tokens.

C_FindObjectsInit

A return value is added: CKR_TEMPLATE_INCONSISTENT

C_DecryptUpdate

A return value is added: CKR_FUNCTION_NOT_PERMITTED

C_EncryptUpdate

A return value is added: CKR_FUNCTION_NOT_PERMITTED

C_UnblockPIN

CK_RV C_UnblockPIN (CK_SESSION_HANDLE hSession, CK_CHAR_PTR pPin, CK_ULONG ulPinLen, CK_CHAR_PTR pPuk, CK_ULONG ulPukLen);
This function is not a member of the PKCS#11 v2.20 specification. It can be used to unblock a locked PIN.

  • hSession is an ordinary session handle.

  • pPin should point to a buffer containing the PIN. It depends on the token whether this should be the old PIN or a new PIN.

  • pPuk is a pointer to the unblocking code.

C_InitTokenPPA

CK_RV C_InitTokenPPA (CK_SLOT_ID slotID, CK_CHAR_PTR pScript, CK_ULONG ulScriptLen, CK_CHAR_PTR pVariables, CK_ULONG ulVariables);
This function is not a member of the PKCS#11 v2.20 specification. It can be used to initialize a token using a card script.

  • slotID is the slot containing the token to be initialized.

  • pScript is the script, as one long string.

  • ulScriptLen is the length of pScript.

  • pVariables is an optional map of variables to be used in the script. This is almost equal to having the same variables and corresponding values at the top of the script. Each value of the map must appear as it would within the script, for example, strings must have quotes, etc. As with variables within the script, a variable may not be re-defined, that is, it must appear either in the map or in the script (some secure variables are excepted from this rule). See"Serialization of Java map" for details on the syntax of the map. May be null.

  • ulVariables is the size of pVariables. If pVariables is null, this is ignored.

C_GetProperty

CK_RV C_GetProperty (CK_SESSION_HANDLE hSession, CK_CHAR_PTR pProperty, CK_CHAR_PTR pResult, CK_ULONG_PTR pulPropLen);
This function is not a member of the PKCS#11 v2.20 specification. It can be used to get various properties that are out of scope for the PKCS#11 specification.

  • hSession is the session.

  • pProperty is a null-terminated string identifying the property to search for.

  • pResult is the result sent in return.

  • pulPropLen is the length of the resulting property.

  • See “Properties” for details on the available properties.

C_SetSlotProperty

CK_RV C_SetSlotProperty (CK_SLOT_ID slotID, CK_CHAR_PTR pProperty, CK_CHAR_PTR pValue, CK_ULONG pulValue);
Sets a property on a slot. slotID defines the slot, and must be a valid slot.

  • pProperty is a null-terminated string identifying the property (may not be null).

  • pValue is the value to which to set the property, and pulValue is its length.

  • See “Properties” for details on the available properties, and how to define their values.

  • If the specified property can not be set (for example, the name of the property is unknown), CKR_ATTRIBUTE_VALUE_INVALID is returned.

Serialization of Java map

The C_InitTokenPPA function takes an optional map of variables, as a map serialized to a byte array. The format of the serialization is:

  • For each key-value pair in the map a 0x01 byte precedes the key.

  • After a key, a 0x02 byte precedes the corresponding value.

  • If the value is empty (that is, consists of no data at all), the 0x02 byte is optional.

  • At the very end of the map a 0x03 byte marks the end.

  • If a key or value contains one or more 0x01, 0x02, 0x03 or 0xB1 bytes, each one must be “escaped” by prefixing it with a 0xB1 byte.

  • Keys must be unique, that is, no key value may appear more than once.

Neither keys nor values are null-terminated; their lengths are specified by the appearances of the “special” bytes.

The syntax for a map containing n key-value pairs may be described as:

0x01 <key 1> [ 0x02 <value 1> ] 0x01 <key 2> [ 0x02 <value 2> ] . . . 0x01 <key n> [ 0x02 <value n> ] 0x03

PIN data URI

According to the PKCS#11 specification, PINs should contain only UTF-8 characters. However, under certain circumstances it is required to use PINs that are not valid UTF-8 strings. For example factory Management Key on the PIV card is derived from the PIV Context Value using symmetric encryption algorithm and is not a valid UTF-8 string. Personal Desktop PKCS#11 module uses PIV Management Key as PIN for CKU_SO user and needs to bypass this limitation. For this purpose PIN can be encoded using data URI scheme.

The syntax of data URIs was defined in RFC 2397, and follows the URI scheme syntax. A data URI consists of:

data:[<media type>][;charset=<character set>][;base64],<data>

Explanation:

  • The scheme, data, is followed by a colon (:)

  • <media type> optional, at the moment this parameter is ignored.

  • <character set> optional, at the moment this parameter is ignored.

  • base64 optional. separated from the preceding part by a semicolon (;). When present, this indicates that the <data> of the URI is encoded using Base64 scheme.

  • <data> the actual data, separated from the preceding part by a comma (,).

Below are some valid examples of PIN encoded with data URI scheme:

"data:,12345" // PIN is "12345" "data:text/plain;base64,MTIzNDU=" // PIN is "12345" "data:text/plain;charset=US-ASCII;base64,MTIzNDU=" // PIN is "12345" "data:text/plain;base64,ABEiM0RV" // PIN is 0x001122334455 (binary) "data:;base64,MTIzNDU2" // PIN is "123456"

These API functions support PIN data URI:

  • C_Login

  • C_SetPIN

  • C_UnblockPIN

If a UTF-8 string passed as a parameter for one of the above API functions does not match the data URI scheme, it will be handled as an usual PIN according to PKCS#11 specification.

Properties

This table describes the properties that can be used with Personal Desktop's PKCS#11 module, and whether they can be gotten (using C_GetProperty) and/or set (using C_SetSlotProperty).

Key

Get

Set (Slot)

Description

Key

Get

Set (Slot)

Description

ChipSerialNumber

 

Gets a card's chip serial number. Only works for sessions whose slots contain a smart card type token.

smkey

 

Sets an SM (Secure Messaging) key. After such a key has been set, communication with a card will use Secure Messaging. Should only be set on slots that contain a smart card token. Should be set before C_OpenSession.

Header file

The following header file can be used for programming against Personal Desktop's PKCS#11 module:

PKCS#11 Interoperability with PIV cards

This section describes PKCS#11 features specific to PIV (Personal Identity Verification) cards supported by Personal Desktop.

Context value by card Issuer

Some card manufacturers provide special “context value” that can be used for key diversification. This value can be read using Personal Desktop's PKCS#11 API:

PIN mapping

There are 3 types of PIN supported by the C_Login function. They are mapped to PIV authentication objects in the following ways:

PKCS#11 PIN

PIV authentication object

PKCS#11 PIN

PIV authentication object

CKU_USER

PIV PIN

CKU_SO

PIV Management Key

CKU_CONTEXT_SPECIFIC

PIV PUK

PINs that aren't UTF-8 strings must be encoded in a Data URI, see “PIN Data URI”.

Key generation

After calling C_GenerateKeyPair, the public key is stored in Personal Desktop's memory until the application is closed or the card is removed. The public key is not written to the card because PIV cards do not have containers for public keys. The calling application must save the public key elsewhere for issuing the certificate.

Additional information

Copyright 2024 Technology Nexus Secured Business Solutions AB. All rights reserved.
Contact Nexus | https://www.nexusgroup.com | Disclaimer | Terms & Conditions