Class: PKCS11

PKCS11()

new PKCS11()

PKCS11 add-on object. The constructor is used internaly. The web application must invoke the 'Create' function of this API to create the instance.
Source:

Methods

C_CloseAllSessions(slotId, callback)

Closes all sessions an application has with a token.
Parameters:
Name Type Description
slotId Number is the slot identifier.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following status (" + status + ")";
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    slotId = 0; // Slot identifer as returned by the C_GetSlotList function
theObjectPKCS11.C_CloseAllSession(slotId, callback);

C_CreateObject(sessionHandle, attributes, callback)

Creates a new object from a given template.
Parameters:
Name Type Description
sessionHandle Number session identifier.
attributes Object JSON object containing all the attributes of the object to create. The attribute name is described into the PKCS11 specification. All available attributes are described with the prefixe "CKA_". The attribute value can be a boolean (with value true or false), a number, a string or a byte array.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Returns:
The success function of the callback returns an object data with the property key 'objectHandle' containing the value of the created object.
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following the object handle (" + data.objectHandle + ")";
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    sessionHandle = 22222222, // A valid session handle provided by C_OpenSession
    attributesData;

// The attribute name is any CKA_ characteristic as defined in the PKCS11 specification
// The attribute value can be a boolean (with value true or false), a number, a string or a byte array.
// Here is the create a data object using the attributes CKA_CLASS, CKA_TOKEN, CKA_APPLICATION and CKA_VALUE.
attributesData.CKA_CLASS = 0;
attributesData.CKA_TOKEN = true;
attributesData.CKA_APPLICATION = [84, 101, 115, 116, 32, 65, 112, 112, 108, 105, 99, 97, 116, 105, 111, 110];
attributesData.CKA_VALUE = [84, 104, 105, 115, 32, 105, 115, 32, 116, 104, 101, 32, 118, 97, 108, 117, 101, 32, 111, 102, 32, 116, 104, 101, 32, 100, 97, 116, 97, 32, 111, 98, 106, 101, 99, 116];
attributesData.CKA_LABEL = [84, 104, 105, 115, 32, 105, 115, 32, 116, 104, 101, 32, 108, 97, 98, 101, 108, 32, 111, 102, 32, 116, 104, 101, 32, 100, 97, 116, 97, 32, 111, 98, 106, 101, 99, 116];
theObjectPKCS11.C_CreateObject(sessionHandle, attributesData, callback);

C_Decrypt(sessionHandle, keyObjectHandle, mechanismType, data, callback)

Decrypts encrypted data in a single part. This function invokes internally the C_DecryptInit, C_Decrypt and C_DecryptFinal functions and sends back the result.
Parameters:
Name Type Description
sessionHandle Number session identifier.
keyObjectHandle Number object handle of the key that is used for decryption.
mechanismType Number mechanism type to use for decryption.
data Array byte array containing the buffer to decrypt.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Returns:
The success function of the callback returns an 'buffer' byte array containing the decrypted data.
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following the decrypted data (" + JSON.stringigy(data.buffer) + ")";
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    sessionHandle = 22222222, // A valid session handle provided by C_OpenSession
    keyObjectHandle = 3333333, // A valid object handle provided by C_FindObjects or C_GenerateKeyPair for example
    mechanismType = 1, // Value of CKM_RSA_PKCS as described in the PKCS11 specification
    encryptedData = [12,13,14,15,16];
    
theObjectPKCS11.C_Decrypt(sessionHandle, keyObjectHandle, mechanismType, encryptedData, callback);

C_DestroyObject(sessionHandle, objectHandle, callback)

Destroys an object.
Parameters:
Name Type Description
sessionHandle Number session identifier.
objectHandle Number handle of the object to delete.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following the status (" + status + ")";
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    sessionHandle = 22222222, // A valid session handle provided by C_OpenSession
    objectHandle = 12;
    
theObjectPKCS11.C_DestroyObject(sessionHandle, objectHandle, callback);

C_Encrypt(sessionHandle, keyObjectHandle, mechanismType, data, callback)

Encrypts data in a single part. This function invokes internally the C_EncryptInit, C_Encrypt and C_EncryptFinal functions and sends back the result.
Parameters:
Name Type Description
sessionHandle Number session identifier.
keyObjectHandle Number object handle of the key that is used for encryption.
mechanismType Number mechanism type to use for encryption.
data Array byte array containing the buffer to encrypt.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Returns:
The success function of the callback returns a byte array 'buffer' containing the encrypted data.
Example
var callback = {
 
        success : function (status, data) {

            var message = "The function returned the following the encrypted data (" + JSON.stringigy(data.buffer) + ")";
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    sessionHandle = 22222222, // A valid session handle provided by C_OpenSession
    keyObjectHandle = 3333333, // A valid object handle provided by C_FindObjects or C_GenerateKeyPair for example
    mechanismType = 1, // Value of CKM_RSA_PKCS as described in the PKCS11 specification
    data =[12,13,14,15,16];
    
theObjectPKCS11.C_Encrypt(sessionHandle, keyObjectHandle, mechanismType, data, callback);

C_FindObjects(sessionHandle, attributes, callback)

Searches for token and session objects that match a template. This function invokes internally the C_FindObjectsInit, C_FindObjects and C_FindObjectsFinal functions and sends back the result.
Parameters:
Name Type Description
sessionHandle Number session identifier.
attributes Object JSON object containing all the attributes to search for. The attribute can be a boolean (with value true or false), a number, a string or a byte array.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Returns:
The success function of the callback returns an array of object handles matching the searched attributes.
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following the object handles:";
            for(var key in data) {
                message += "object (" + data[key] + ")";
            }
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    sessionHandle = 22222222, // A valid session handle provided by C_OpenSession
    attributes;

// Search all the CKO_DATA available in the token
attributes.CKA_CLASS = 0;
    
theObjectPKCS11.C_FindObjects(sessionHandle, attributes, callback);

C_GenerateKeyPair(sessionHandle, mechanismType, attributesPublicKey, attributesPrivateKey, callback)

Generates a public/private key pair, creating new key objects.
Parameters:
Name Type Description
sessionHandle Number session identifier.
mechanismType Number mechanism type to use for generation.
attributesPublicKey Object JSON object containing the attributes of the public key.
attributesPrivateKey Object JSON object containing the attributes of the private key.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Returns:
The success function of the callback returns the object handles of the new public/private key pair.
Example
var callback = {

        success : function (status, data) {

            // Save key handles for other operations
            publicKeyObjectHandle = data.publicKey;
            privateKeyObjectHandle = data.privateKey;
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    sessionHandle = 22222222, // A valid session handle provided by C_OpenSession
    mechanismType = 0, // Use the CKM_RSA_PKCS_KEY_PAIR_GEN mechanism type for the key generation
    attributesKeyPublic = {},
    attributesKeyPrivate = {},
    signOnly = false; // Flag to create (or not) sign only keys

// Add the attributes describing the public key (see the PKCS11 specification for attributes list, type & usage)
attributesKeyPublic.CKA_MODULUS_BITS = 2048;
attributesKeyPublic.CKA_TOKEN = true;
attributesKeyPublic.CKA_CLASS = 2; // value CKO_PUBLIC_KEY as defined into the PKCKS11 specification
attributesKeyPublic.CKA_KEY_TYPE = 0; // value CKK_RSA as defined into the PKCKS11 specification
attributesKeyPublic.CKA_PRIVATE = false;
attributesKeyPublic.CKA_ENCRYPT = !signOnly;
attributesKeyPublic.CKA_WRAP = !signOnly;
attributesKeyPublic.CKA_VERIFY_RECOVER = true;
attributesKeyPublic.CKA_VERIFY = true;
attributesKeyPublic.CKA_ID = [116, 101, 115, 116, 48, 49]; // Buffer containing the bytes "test01"
attributesKeyPublic.CKA_PUBLIC_EXPONENT = [1, 0, 1];

// Add the attributes describing the private key (see the PKCS11 specification for attributes list, type & usage)
attributesKeyPrivate.CKA_TOKEN = true;
attributesKeyPrivate.CKA_PRIVATE = true;
attributesKeyPrivate.CKA_EXTRACTABLE = false;
attributesKeyPrivate.CKA_SENSITIVE = true;
attributesKeyPrivate.CKA_DECRYPT = !signOnly;
attributesKeyPrivate.CKA_UNWRAP = !signOnly;
attributesKeyPrivate.CKA_SIGN_RECOVER = true;
attributesKeyPrivate.CKA_SIGN = true;
attributesKeyPrivate.CKA_ID = [116, 101, 115, 116, 48, 49];

theObjectPKCS11.C_GenerateKeyPair(sessionHandle, mechanismType, attributesKeyPublic, attributesKeyPrivate, generateKeyPairCallback);

C_GetAttributeValue(sessionHandle, objectHandle, attributes, callback)

Obtains the value of one or more attributes of an object.
Parameters:
Name Type Description
sessionHandle Number session identifier.
objectHandle Number handle of the object to get attribute from.
attributes Object CK_ATTRIBUTE_TYPE array containing all the attributes to get.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following the attributes :";
            for(var key in data) {
                message += "attribute (" + key + ") - value (" + data[key] + ")";
            }
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    sessionHandle = 22222222, // A valid session handle provided by C_OpenSession
    objectHandle = 12,
    // Set a byte array to get the CKA_CLASS (0x00000000), CKA_TOKEN (0x00000001) and CKA_VALUE (0x00000011) attribute of the object
    attributes = [0, 1, 11];
    
theObjectPKCS11.C_GetAttributeValue(sessionHandle, objectHandle, attributes, callback);

C_GetSessionInfo(sessionHandle, callback)

Obtains information about a session.
Parameters:
Name Type Description
sessionHandle Number session identifier.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Returns:
The success function of the callback returns CK_SESSION_INFO JSON object: { "slotId" : Number, "state" : Number, "flags" : Number, "deviceError" : Number }
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following CK_SESSION_INFO object: ";
            message += "slot id (" + data.slotId + ")";
            message += "state (" + data.state + ")";
            message += "flags (" + data.flags + ")";
            message += "deviceError (" + data.deviceError + ")";
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    sessionHandle = 2;
theObjectPKCS11.C_GetSessionInfo(sessionHandle, callback);

C_Login(sessionHandle, userType, pin, callback)

Logs a user into a token.
Parameters:
Name Type Description
sessionHandle Number session identifier.
userType Number is the user type (standard user, security officer).
pin String is the user's PIN as plain text.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following status (" + status + ")";
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    sessionHandle = 22222222, // A valid session handle provided by C_OpenSession
    userType = 1,
    pin = "1234";
theObjectPKCS11.C_Login(sessionHandle, userType, pin, callback);

C_Logout(sessionHandle, callback)

Logs a user out from a token.
Parameters:
Name Type Description
sessionHandle Number session identifier.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following status (" + status + ")";
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    sessionHandle = 2;
theObjectPKCS11.C_Logout(sessionHandle, callback);

C_SetAttributeValue(sessionHandle, objectHandle, attributes, callback)

Modifies the value of one or more attributes of an object.
Parameters:
Name Type Description
sessionHandle Number session identifier.
objectHandle Number handle of the object to get attribute from.
attributes Object JSON object containing all the attributes to set. The attribute can be a boolean (with value true or false), a number, a string or a byte array.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following the attributes :";
            for(var i in data) {
                message += "attribute (" + i + ") - value (" + data[i] + ")";
            }
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    sessionHandle = 22222222, // A valid session handle provided by C_OpenSession
    objectHandle = 12,
    attributes;
    
// The attribute can be a boolean (with value true or false), a number, a string or a byte array.
attributes.CKA_CLASS = 0;
attributes.CKA_TOKEN = true;
attributes.CKA_LABEL = [12,13,14,15,16];

theObjectPKCS11.C_SetAttributeValue(sessionHandle, objectHandle, attributes, callback);

C_Sign(sessionHandle, keyObjectHandle, mechanismType, data, callback)

Signs data in a single part. This function invokes internally the C_SignInit and C_Sign functions and sends back the result.
Parameters:
Name Type Description
sessionHandle Number session identifier.
keyObjectHandle Number object handle of the key that is used for signature.
mechanismType Number mechanism type to use for signature.
data Array byte array containing the buffer to sign.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Returns:
The success callback returns a byte array 'buffer' containing the signature.
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following the signature (" + JSON.stringigy(data.buffer) + ")";
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    sessionHandle = 22222222, // A valid session handle provided by C_OpenSession
    keyObjectHandle = 3333333, // A valid object handle provided by C_FindObjects or C_GenerateKeyPair for example
    mechanismType = 1, // Use the CKM_RSA_PKCS mechanism type for the signature
    data = [12,13,14,15,16]; // Byte array to sign
    
theObjectPKCS11.C_Sign(sessionHandle, keyObjectHandle, mechanismType, data, callback);

C_Verify(sessionHandle, keyObjectHandle, mechanismType, data, signature, callback)

Verifies signature in a single part. This function invokes internally the C_VerifyInit, C_Verify and C_VerifyFinal functions and sends back the result.
Parameters:
Name Type Description
sessionHandle Number session identifier.
keyObjectHandle Number object handle of the key that is used for signature.
mechanismType Number mechanism type to use for signature.
data Array byte array containing the original buffer used to generate the signature.
signature Array byte array containing the signature to verify.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Returns:
The success callback returns a status.
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following the status (" + status + ")";
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    sessionHandle = 22222222, // A valid session handle provided by C_OpenSession
    keyObjectHandle = 3333333, // A valid object handle provided by C_FindObjects or C_GenerateKeyPair for example
    mechanismType = 1, // Use the CKM_RSA_PKCS mechanism type for the signature
    data = [12,13,14,15,16], // Original buffer used to generate the signature
    signature = [67, ... , 134]; // signature byte buffer returned by the C_Sign function
    
theObjectPKCS11.C_Verify(sessionHandle, keyObjectHandle, mechanismType, data, signature, callback);

dispose()

Disposes the PKCS11 instance. This function must be invoked by the web application when the PKCS11 instance is no more usefull.
Source:
Example
var finalStopTokenEventHandlerCallback = {

    success: function () {

        console.log('StopTokenEventHandler success');

        // Release the PKCS11 object
        if (theObjectPKCS11) {
            theObjectPKCS11.C_Finalize();
            theObjectPKCS11.dispose();
        }
    },

    error: function (code) {

        console.log('StopTokenEventHandler failed ' + code);
    }
};


function onPageUnload() {

    'use strict';

    // Stop the PKCS11 event handler first to release the PKC11
    SConnect.PKCS11.StopTokenEventHandler(finalStopTokenEventHandlerCallback);
}

ETC_DeviceIOCTL(slotId, code, data, callback)

Invokes a device's IOCTL proprietary function.
Parameters:
Name Type Description
slotId number slot identifier
code number code of the IOCTL function.
Use the code 15 to invoke the 'get SWYS device charactericts'.
data object input parameters to provide to the IOCTL function (if required by the IOCTL function).
With code 15 no data is required.
callback object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Returns:
The success function of the callback returns the result of the IOCTL function invocation.
With code 15 the result is an object with all the device characteristics & SWYS features (@see ETC_GetDeviceInformation).
Example
// Retrieve the device's SWYS charactericts
 var slotId = 0,
    ETCK_IODEV_GET_SWYS_INFO = 15;
 theObjectPKCS11.ETC_DeviceIOCTL(slotId, ETCK_IODEV_GET_SWYS_INFO, null, callback);

ETC_EnableAuthenticationPopup(flag, callback)

Enables/disables the Gemalto inner popup window displayed during C_Login operation.
This function must be invoked after the session is opened (C_OpenSession).
Parameters:
Name Type Description
flag boolean true to enable and show the Gemalto popup window, false to disable and hide it.
callback object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Example
var callback = {
        success : function (status, data) {
            alert("The function successed");
        },
        error : function (errorCode) {
            alert("The function failed with code (" + errorCode + ")");
        }
    },
    flag = false;
    
theObjectPKCS11.ETC_EnableAuthenticationPopup(flag, callback);

ETC_GetDeviceCertificates(sessionHandle, certificateCategory, callback)

Search for the certificates owned by the device itself
Parameters:
Name Type Description
sessionHandle number session identifier
certificateCategory number specifies the category of the searched certificate.
As described into the PKCS11 specification for values of the CKA_CERTIFICATE_TYPE attribute, the certificate category can be:
  • 0 = unspecified (default value)
  • 2 = authority (CA certificates)
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Returns:
The success function of the callback returns the object handle(s) of the device certificate(s).
Example
var callback = {
        success : function (status, data) {

            // Save key handles for other operations
            publicKeyObjectHandle = data.publicKey;
            privateKeyObjectHandle = data.privateKey;
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    sessionHandle = 22222222,
    certificateCategory = 2; // Search for CA certificates 
theObjectPKCS11.ETC_GetDeviceCertificate(sessionHandle, certificateCategory, callback);

ETC_GetRetryCounter(sessionHandle, callback)

Retrieves the user PIN retry counter.
Parameters:
Name Type Description
sessionHandle number session identifier.
callback object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Returns:
The success callback returns a property 'ETCKA_RETRY_USER' containing the user's PIN retry counter as a number.
Example
var callback = {
        success : function (status, data) {
            alert("The retry counter is " + data.ETCKA_RETRY_USER);
        },
        error : function (errorCode) {
            alert("The function failed with code (" + errorCode + ")");
        }
    },
    flag = false;
    
theObjectPKCS11.ETC_GetRetryCounter(sessionHandle, callback);

ETC_SignEx(sessionHandle, keyObjectHandle, data, certificateObjectHandle, hidden, hash, signaturePKI, callback)

Signs data in a single part using CKM_RSA_PKCS as signature mechanism and CKM_SHA256 as hash mechansim. This function invokes internally the C_SignInit and ETC_SignEx functions and sends back the result.
Parameters:
Name Type Description
sessionHandle number session identifier.
keyObjectHandle number object handle of the key that is used for signature.
data Array byte array containing the buffer to sign.
certificateObjectHandle number Object handle of the terminal certificate.
hidden Array byte array containing the hidden data
hash Array byte array containing the hash
signaturePKI boolean true for PKI signature, false for OCRA OTP signature
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Returns:
The success callback returns a byte array 'signatureTerminal' containing the signature provided by the terminal and a byte array 'signatureCard' containing the signature provided by the smart card.
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following the signature (" + JSON.stringigy(data.buffer) + ")";
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    sessionHandle = 22222222, // A valid session handle provided by C_OpenSession
    keyObjectHandle = 3333333, // A valid object handle provided by C_FindObjects or C_GenerateKeyPair for example
    data = [41,6D,6F,75,6E,74,3A,0A,31,32,30,30,2C,30,30], // Byte array to sign
    certificateObjectHandle = 77777, // A valid certificate object handle returned by the function 'ETC_GetDeviceCertificate'
    hidden = [32,30,31,35,30,33,33,30,5F,31,36,30,37,32,32], 
    hash = [47,C1,76,D2,22,9F,BB,71,33,6C,D7,23,2A,D4,40,ED,B0,38,A6,6D,8A,05,03,22,67,AC,33,B5,D1,F0,9F,50],
    signaturePKI = true;
    
theObjectPKCS11.ETC_SignEx(sessionHandle, keyObjectHandle, data, certificateObjectHandle, hidden, hash, signaturePKI, callback);

(static) C_CloseSession(sessionHandle, callback)

Closes a session between an application and a token in a particular slot.
Parameters:
Name Type Description
sessionHandle Number session identifier.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following status (" + status + ")";
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    sessionHandle = 2;
theObjectPKCS11.C_CloseSession(sessionHandle, callback);

(static) C_Finalize(callback)

Disposes the PKCS#11 library.
Parameters:
Name Type Description
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Example
var callback = {

        success : function (status, data) {

            alert("The function returned the CK_RV (" + status + )");
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    };
theObjectPKCS11.C_Finalize(callback);

(static) C_GetInfo(callback)

Returns general information about Cryptoki.
Parameters:
Name Type Description
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Returns:
The success function of the callback returns CK_INFO JSON object: 
 {
    "cryptokiVersion" : {
        "major" : TypeNumber,
        "minor" : TypeNumber,
        },
    "manufacturerID" : TypeString,
    "flags" : TypeNumber,
    "libraryDescription" : TypeString,
    "libraryVersion" : {
        "major" : TypeNumber,
        "minor" : TypeNumber,
        }
 }
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following CK_INFO information:";
            message + "cryptokiVersion (" + data.cryptokiVersion.major + " - " + data.cryptokiVersion.major + ")";
            message + "manufacturerID (" + data.manufacturerID + ")";
            message + "flags (" + data.flags + ")";
            message + "libraryDescription (" + data.libraryDescription + ")";
            message + "libraryVersion (" + data.libraryVersion.major + " - " + data.libraryVersion.major + ")";
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    };
theObjectPKCS11.C_GetInfo(callback);

(static) C_GetMechanismInfo(slotId, mechanismType, callback)

Obtains information about a particular mechanism possibly supported by a token.
Parameters:
Name Type Description
slotId Number slot identifier.
mechanismType Number mechanism type to get information about.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Returns:
The success function of the callback returns CK_MECHANISM_INFO JSON object: 
 {
    "minKeySize" : TypeNumber,
    "maxKeySize" : TypeNumber,
    "flags" : Number
 }
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following CK_MECHANISM_INFO information:";
            message + "minKeySize (" + data.minKeySize + ")";
            message + "maxKeySize (" + data.maxKeySize + ")";
            message + "flags (" + data.flags + ")";
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    mechanismType = 1, 
    slotId = 1;
    
theObjectPKCS11.C_GetMechanismInfo(slotId, mechanismType, callback);

(static) C_GetMechanismList(slotId, callback)

Obtains the list of mechanism types supported by a token.
Parameters:
Name Type Description
slotId Number slot identifier.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Returns:
The success function of the callback returns a [1..n] JSON array of Numbers for the CK_MECHANISM_TYPE available accordingly the 'slotId' parameter provided. For example the PKCS11 add-on sends back the array [0, 1, 6] if the mechanism types CKM_RSA_PKCS_KEY_PAIR_GEN, CKM_RSA_PKCS and CKM_SHA1_RSA_PKCS are available.
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following CK_MECHANISM_TYPE: ";
            for (var i = 0, len = data.length; i < len; i++) {
                message += " " + data[i];
            }
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    slotId = 1;
theObjectPKCS11.C_GetMechanismList(slotId, callback);

(static) C_GetSlotInfo(slotId, callback)

Obtains information about a particular slot in the system.
Parameters:
Name Type Description
slotId Number slot identifier.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Returns:
The success function of the callback returns CK_SLOT_INFO JSON object: 
 {
    "slotDescription" : TypeString,
    "manufacturerID" : TypeString,
    "flags" : TypeNumber,
    "hardwareVersion" : {
        "major" : TypeNumber,
        "minor" : TypeNumber,
        },
    "firmwareVersion" : {
        "major" : TypeNumber,
        "minor" : TypeNumber,
        }        
 }
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following CK_SLOT_INFO information:";
            message + "cryptokiVersion (" + data.cryptokiVersion.major + " - " + data.cryptokiVersion.major + ")";
            message + "manufacturerID (" + data.manufacturerID + ")";
            message + "flags (" + data.flags + ")";
            message + "libraryDescription (" + data.libraryDescription + ")";
            message + "libraryVersion (" + data.libraryVersion.major + " - " + data.libraryVersion.major + ")";
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    slotId = 1;
theObjectPKCS11.C_GetSlotInfo(slotId, callback);

(static) C_GetSlotList(tokenPresent, callback)

Returns a list of slots in the system.
Parameters:
Name Type Description
tokenPresent Boolean indicates whether the list obtained includes only those slots with a token present (true), or all slots (false).
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Returns:
The success function of the callback returns a [1..n] JSON array of Numbers for the CK_SLOT_ID available with or without token inserted accordingly the 'tokenPresent' parameter provided. For example the PKCS11 add-on sends back the array [1, 2, 3] if the slot with the identifier 1 and the slot with identifier 2 and the slot woth identifier 3 are available.
Example
var callback = {

        success : function (status, data) {

            var message = "The available slots are :";
            for (var i = 0, len = data.length; i < len; i++) {
              message += data[i];
              message += " ";
            }
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    tokenPresent = true;
theObjectPKCS11.C_GetSlotList(tokenPresent,callback);

(static) C_GetTokenInfo(slotId, callback)

Obtains information about a particular token in the system.
Parameters:
Name Type Description
slotId Number slot identifier.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Returns:
The success function of the callback returns CK_TOKEN_INFO JSON object: 
 {
    "label" : TypeString,
    "manufacturerID" : TypeString,
    "model" : TypeString,
    "serialNumber" : TypeString,
    "flags" : TypeNumber,
    "maxSessionCount" : TypeNumber,
    "sessionCount" : TypeNumber,
    "maxRwSessionCount" : TypeNumber,
    "rwSessionCount" : TypeNumber,
    "maxPinLen" : TypeNumber,
    "minPinLen" : TypeNumber,
    "totalPublicMemory" : TypeNumber,
    "freePublicMemory" : TypeNumber,
    "totalPrivateMemory" : TypeNumber,
    "freePrivateMemory" : TypeNumber,
    "hardwareVersion" : {
        "major" : TypeNumber,
        "minor" : TypeNumber,
        },
    "firmwareVersion" : {
        "major" : TypeNumber,
        "minor" : TypeNumber,
        },        
    "time" : String
 }
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following CK_TOKEN_INFO information:";
            message + "label (" + data.label + ")";
            message + "manufacturerID (" + data.manufacturerID + ")";
            message + "model (" + data.model + ")";
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    slotId = 1;
theObjectPKCS11.C_GetTokenInfo(slotId, callback);

(static) C_Initialize(callback)

Initializes the PKCS#11 library.
Parameters:
Name Type Description
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Example
var callback = {

        success : function (status, data) {

            alert("The function returned the CK_RV (" + status + )");
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    };
theObjectPKCS11.C_Initialize(callback);

(static) C_InitPIN(sessionHandle, pin, callback)

Initializes the normal user’s PIN.
Parameters:
Name Type Description
sessionHandle Number is the handle of the session.
pin String is the normal user’s PIN formated as plain text.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following status (" + status + ")";
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    sessionHandle = 22222222, // A valid session handle provided by C_OpenSession
    pin = "1234";
theObjectPKCS11.C_InitPIN(sessionHandle, pin, callback);

(static) C_OpenSession(slotId, flags, callback)

Opens a session between an application and a token in a particular slot.
Parameters:
Name Type Description
slotId Number is the slot identifier.
flags Number indicates the type of session (read, read/write, serial).
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following status (" + status + ")";
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    // Prepare to open a session on the slotId 1
    slotId = 1,
    // Prepare the flags to open a RW session (CKF_SERIAL_SESSION | CKF_RW_SESSION = 6)
    flags = 6;
theObjectPKCS11.C_OpenSession(slotId, flags, callback);

(static) C_SetPIN(sessionHandle, oldPin, newPin, callback)

Modifies the PIN of the user that is currently logged in, or the CKU_USER PIN if the session is not logged in.
Parameters:
Name Type Description
sessionHandle Number is the handle of the session.
oldPin String is the old user’s PIN formated as plain text.
newPin String is the new user’s PIN formated as plain text.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Example
var callback = {

        success : function (status, data) {

            var message = "The function returned the following status (" + status + ")";
            alert(message);
        },
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    },
    sessionHandle = 22222222, // A valid session handle provided by C_OpenSession
    oldPin = "1234",
    newPin = "5678";
theObjectPKCS11.C_SetPIN(sessionHandle, oldPin, newPin, callback);

(static) Create(callback)

Creates the PKCS11 add-on instance. The returned instance by the 'success' callback exposes the PKCS11 API to the web application.
Parameters:
Name Type Description
callback Object object called when the operation is finished
  • callback.success(pkcs11) - function called when SConnect PKCS11 add-on instance creation is successful
  • callback.error(errorcode) - function called when SConnect PKCS11 add-on instance creation is failed
Source:
Example
// Define a global PKCS11 object instance to use in the web application
 var theObjectPKCS11 = null,
    // Define the server configuration to use by SConnect to check or get SConnect installers and add-ons
    // In this example the SConnect component are stored at the URL "https://your-web-server-url/path-to-your-SConnect-repository"
    serverConfiguration = {
        // Mind to modify the URL to connect to your web server.
        // THE "impPath", "extPath", "eulaPath", "faqPath" AND "addonPath" URLS ARE ALWAYS ABSOLUTE PATH.
        imgPath: "https://your-web-server-url/path-to-your-SConnect-repository/images/",
        extPath: "https://your-web-server-url/path-to-your-SConnect-repository/extensions/",
        eulaPath: "https://your-web-server-url/path-to-your-SConnect-repository/eula/",
        faqPath: "https://your-web-server-url/path-to-your-SConnect-repository/faq/",
        addonPath: "https://your-web-server-url/path-to-your-SConnect-repository/addons/"
        // Mind to modify the licensePath URL accordingdly to your web server.
        // THE LICENSE PATH IS ALWAYS RELATIVE PATH.
        //,licensePath : "/sconnect.lic"
    };

 var initializeCallback = {

    success: function (status, data) {

        'use strict';
        alert("SConnect installed, PKCS11 add-on installed and C_Initialize succeeded");
         SConnect.PKCS11.StartTokenEventHandler(tokenEventCallback);
    },

    error: function (status) {
        'use strict';
        log("C_Initialize failed with status " + status);
    }
};

var finalizeCallback = {

    success: function (status, data) {

        'use strict';
        // C_Finalize done !
    },

    error: function (status) {
        'use strict';
        alert("C_Finalize failed with status " + status);
    }
};

var createCallback = {

    success: function (p11) {
        'use strict';
        theObjectPKCS11 = p11;

        theObjectPKCS11.C_Initialize(initializeCallback);
    },

    error: function (code) {
        'use strict';
        log('failed to create sac instance, reason: ' + code);
    }
};

var tokenEventCallback = {

    onTokenInsertion: function (resp) {
        'use strict';
        log('onTokenInsertion - slotId (' + resp.slotId + ')');
        log('onTokenInsertion - label (' + resp.label + ')');
    },

    onTokenRemoval: function (resp) {
        'use strict';
        log('onTokenRemoval - slotId (' + resp.slotId + ')');
        log('onTokenRemoval - label (' + resp.label + ')');
    }
};



var installAddOnsCallback = {

    success: function () {

        'use strict';
        SConnect.PKCS11.Create(createCallback);
    },

    error: function (code, info) {
        'use strict';
        alert('install-addons-failed, reason: ' + code);
    }
};

var validateCallback = {

    success: function () {
        'use strict';
        SConnect.InstallAddOns([new SConnect.PKCS11Info()], installAddOnsCallback);
    },

    error: function (code) {
        'use strict';
        alert('validate-server-failed, reason: ' + code);
    }
};

function onPageLoad() {

    'use strict';

    var installCallback = {

        success: function () {
            SConnect.ValidateServer(validateCallback);
        },

        error: function (code) {
            alert('sconnect-install-failed, reason: ' + code);
        }
    };

    // Configure the path to reach the SConnect components
    SConnect.ConfigResources(serverConfiguration);

    // Start the SConnect initialization or the automatic installation if SConnect is not installed on the end-user computer
    SConnect.Install(installCallback);
}


//Releases all SConnect & PKCS11 resources
function onPageUnload() {

    'use strict';

    // Stop the PKCS11 event handler
    SConnect.PKCS11.StopTokenEventHandler();

    // Release the PKCS11 object
    if (theObjectPKCS11) {
        theObjectPKCS11.C_Finalize(finalizeCallback);
        theObjectPKCS11.dispose();
    }
}


// Initialize the SConnect & PKCS11 addon when the web page is load
window.onload = onPageLoad;


// Release all resources when the page is unload
window.onunload = onPageUnload;

(static) ETC_GetDeviceInformation(slotId, callback) → {object}

Returns SWYYS information about a slot.
Parameters:
Name Type Description
slotId number slot identifier
callback object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:
Returns:
The success callback function returns an object containing the following properties: 
 {
    // SWYS definition version
    "swysVersion" : {
        "major" : TypeNumber,
        "minor" : TypeNumber,
        },
    // ASCII Code FW version
    "fwVersion" : TypeString,
    // Number of rows, BCD coded
    "rows" : TypeNumber,
    // Number of columns, BCD coded
    "columns" : TypeNumber,
    // Supported ISO8859 tables, one Number each, e.g. 0x0F for ISO8859-15
    "isoCharTables" : TypeArray of TypeNumber,
    // Supported languages tables, one String each, ASCII coded according to ISO639-1
    "languages" : TypeArray of TypeString,
    // Serial number, blank padded, ASCII coded
    "serialNumber" : TypeString,
    // Support for Hashing. '01': Only SHA256,'02': Only SHA512,'03': both
    "hashSupport" : TypeNumber,
    // Support for PKI. '01': Only OATH OCRA OTP,'02': Only PKI Signature, '03':both
    "pkiSupport" : TypeNumber,
    // Card serial number, blank padded, ASCII coded
    "cardSerialNumber" : TypeString
 }
Type
object
Example
var slotId = 2,
    callback = {

        success : function (status, data) {

            var message = "The function returned the following SWYS information:";
            message + "swysVersion (" + data.swysVersion.major + " - " + data.swysVersion.major + ")";
            message + "fwVersion (" + data.fwVersion + ")";
            message + "rows (" + data.rows + ")";
            message + "columns (" + data.columns + ")";
            message + "isoCharTables (" + JSON.stringify(data.isoCharTables) + ")";
            message + "languages (" + JSON.stringify(data.languages) + ")";
            message + "serialNumber (" + data.serialNumber + ")";
            message + "hashSupport (" + data.hashSupport + ")";
            message + "pkiSupport (" + data.pkiSupport + ")";
            message + "cardSerialNumber (" + data.cardSerialNumber + ")";
            alert(message);
        },
        
        error : function (errorCode) {

            alert("The function failed with code (" + errorCode + ")");
        }
    };
    
theObjectPKCS11.ETC_GetDeviceInformation(slotId, callback);

(static) ETC_InitTokenFinal(sessionHandle)

Initializes the token.
Parameters:
Name Type Description
sessionHandle Number is the handle of the session.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:

(static) ETC_InitTokenInit(slotId, Label, pin, retryCounter, callback)

Initializes the token.
Parameters:
Name Type Description
slotId Number of the token's slot.
Label String is the label to apply on the token formated as plain text.
pin String is the security officer’s PIN formated as plain text.
retryCounter String is a mandatory value between 0-15 coming from the GUI, not the token.
callback Object object called when the operation is finished.
  • callback.success(status, data) - function called when the function completed successfully
  • callback.error(errorcode) - function called when the function failed
Source:

(static) StartTokenEventHandler(callback)

Starts the listener to the token status change events. This function must be invoked after C_Initialize
Parameters:
Name Type Description
callback Object object called when the event is fired
  • callback.onTokenInsertion(token) - function called when a token insertion event is fired
  • callback.onTokenRemoval(token) - function called when a token removal event is fired
Source:
Example
var tokenEventCallback = {

    onTokenInsertion: function (resp) {
        'use strict';
        log('onTokenInsertion - slotId (' + resp.slotId + ')');
        log('onTokenInsertion - label (' + resp.label + ')');
    },

    onTokenRemoval: function (resp) {
        'use strict';
        log('onTokenRemoval - slotId (' + resp.slotId + ')');
        log('onTokenRemoval - label (' + resp.label + ')');
    }
};

SConnect.PKCS11.StartTokenEventHandler(tokenEventCallback);

(static) StopTokenEventHandler(callback)

Stops the listener to the token status change event. This function must be invoked before C_Finalize.
Parameters:
Name Type Description
callback Object object called when the event is fired
  • callback.success() - function called when listener unregistration is successful
  • callback.error(errorcode) - function called when listener unregistration is failed
Source: