Accessing ePass2003 Auto token through browser

Question

I have got ePass2003 Auto token loaded with self signed certificate. I got lib**.so file to load into firefox and now firefox can list the certificate in token. My requirement is to access the keystore for signing, encryption and decryption i.e public and private key for cryptographic operation on them. May i request guidance on javascript API for doing above cryptographic operation.

Answer 1

Disclosure: I work for CISPL

To access ePass2003 or any Smartcard or Cryptographic USB Token, you need to use Browser Extension. As far as I know, browsers may use the keys from crypto device for TLS handshake. My company provides such extension Signer.Digital Browser Extension. Chrome and Firefox

Windows Host may be downloaded from https://signer.digital/downloads/Signer.Digital.Browser.Extension.Setup.msi

On windows, we don't need PKCS#11 but we use Windows CSP. Thus, USB token driver must be installed on Windows client device for this to work from web browser. lib**.so file is not for Windows but it's for Linux.

Linux host uses this .so file and PKCS#11 to accomplish the task but this is transparent to ePass2003 users and Host application takes care of this.

My requirement is to access the keystore for signing, encryption and decryption i.e public and private key for cryptographic operation on them. May i request guidance on javascript API for doing above cryptographic operation.

I am listing the javascript API (Signer.Digital Version 1.8.0) provides below promises:

1. Select Certificate: This will open popup window to select certificate. certThumbPrint paramater may be provided to select certificate silently.

SignerDigital.getSelectedCertificate(certThumbPrint = "", showExpired = false, keyUsageFilter = 128)

keyUsageFilter values would be as per System.Security.Cryptography.X509Certificates.X509KeyUsageFlags Enum and multiple values may be added (summed).

2. Sign Hash:

SignerDigital.signHash(hash, certAlgorithm, certThumbPrint = "")

3. Sign Authtoken / Data: calculate hash of data and then sign hash.

SignerDigital.signAuthToken(authtoken, certAlgorithm, certThumbPrint = "", showExpired = false)

certAlgorithm is hasing algorithm to be used. ex: "SHA256" or "SHA-256"

showExpired flag may be used here to allow user just login with expired certificate and provide only access to area where user can upload his new certificate.

4. Sign PDF: - Returns PKCS7 signature container

SignerDigital.signPdfHash(hash, certThumbPrint, certAlgorithm)

SignerDigital.signHashCAdESBr(hash, certThumbPrint, certAlgorithm) //for ICP-Brazil

Working of PDF Signing and Digital Signature based Authentication may be tested at https://web.signer.digital/

5. Sign XML:

SignerDigital.signXML(xmlDoc, xmlSignParms, certThumbPrint)

xmlSignParms has wider range of parameters and we provide support for integration on efforts basis.

6. RSA Encrypt: (Using private key of user)

SignerDigital.encryptB64Data(b64Data, useOAEPPadding, certThumbPrint = "", showExpired = false, keyUsageFilter = 32)

Example:

var strToEnc = "Clear Text String to Encrypt.";
var strB64Data = btoa(strToEnc);
console.log("Base64 String of Clear Text String: " + strB64Data);

//Do not provide last parm - certThumbPrint to open dialog to select certificate.
SignerDigital.encryptB64Data(strB64Data, false, "224D7F695ABF0E22EA8D314497F5B56AEFA96FFE") //false for PKCS1 padding, true for OAEP padding
  .then(
    function(EncryptedB64String) { //Success returns xmlSign
      console.log("Encrypted Base64 String: " + EncryptedB64String);
      console.log("Encrypted String: " + atob(EncryptedB64String));
    },
    function(ErrMsg) {
      console.log(ErrMsg);
    }
  )

7. RSA Decrypt: (Using private key of user)

SignerDigital.decryptB64Data(b64Data, useOAEPPadding, certThumbPrint = "", showExpired = false, keyUsageFilter = 32)

Example:

console.log("Encrypted B64 string from server: " + EncB64String);
SignerDigital.decryptB64Data(EncB64String, false, "224D7F695ABF0E22EA8D314497F5B56AEFA96FFE")
  .then(
    function(DecryptedB64String) { //Success returns xmlSign
      console.log("Decrypted Base64 String: " + DecryptedB64String);
      console.log("Decrypted String: " + atob(DecryptedB64String));
    },
    function(ErrMsg) {
      console.log(ErrMsg);
    }
  )
},
error: function(msg) {
  console.debug(msg);
}

8. Sign IT/eTDS Return: (Sign Indian Income Tax/eTDS Return - Same as signHash method, except additional optional param: PAN)

SignerDigital.signITHash(hash, PAN, certThumbPrint = "")

Pass PAN blank to open Select Certificate Dialog. If PAN is nonempty, and certificate for PAN is present, will silently select certerficate.

9. Sign CMS: (Digitally Sign India GST Return)

SignerDigital.signHashCms(hash, certAlgorithm, certIncludeOptions = 2, certThumbPrint = "")

Use method SignerDigital.signHashCAdESBr for ICP-Brazil signature and method SignerDigital.signHashCAdESEg for Egypt ITIDA CAdES-BES signatures.

10. Sign IceGate Data: (Sign IceGate - Indian Customs Data - Json, text, XML)

SignerDigital.signIceGate(b64Data, certThumbPrint = "")

July 2021 Below APIs added for use by Certifying Authorities (CA needs to be enrolled with Signer.Digital Browser Extension)

11. Detect connected smartcard: (Autodetect connected Smartcard or USB Token)

SignerDigital.getPCSCReaders(onlyConnected = true) //List PCSC Readers, set parameter to false if you want to list all available readers

12. Generate CSR: (for Certificate Enrollment in Smartcard or USB Token)

SignerDigital.genCSR(PKCS11Lib, certSubject, certIssuer, keyBits = 2048, hasgAlgorithm = "SHA256", forceUserPinChangeIfDefault = false)

13. Import / Download Certificate (Import User Certificate and Trust Certificate Chain to Smartcard or USB Token)

SignerDigital.importCer(PKCS11Lib, b64Payload, certIssuer)

For more details, code examples of Auto SmartCard detection, genCSR and importCer refer Answer with flow diagram

Update June 2021

Signer.Digital Browser Extension Host Version 1.7.0 now offers better user control to enhance security by asking user about Allowed Origin (website) which is trying to access certificates/keys. Also this version has Auto Update feature so that user automatically gets any security updates/enhancements after approving update by User Account Control dialog.