@evo/vchasno-signer

Vchasno Signer

Library to work with private keys, sign data and verify signatures.

Instalation

npm install -E @evo/vchasno-signer

Usage

import vchasnoSigner from '@evo/vchasno-signer';

// Minimal config for signer, more details you can find in config object section
const configObject = { proxyServiceUrl: '/internal-api/proxy' };

// Initialize signer
await vchasnoSigner.init(configObject);

// Read private key
const key = await vchasnoSigner.readKey(keyFile, password, caServerIdx, certificateFiles);

// Sign data
const eSign = vchasnoSigner.signData(data, key);

// Verify signature
const signInfo = vchasnoSigner.verifySign(data, eSign);

Config object

{
    // Allow to use only power certificates, default is true
    checkIsPowerCertificate: true,
    // Download internal sign library from specific url. If not specified, library
    // will be downloaded from Vchasno servers
    downloadSignLibraryUrl: null,
    // Max data size to work with in bytes, library will take 10x size in memory.
    // *Implicit* default value is 5Mb for desktop and 2Mb for mobile
    maxFileSize: undefined,
    // By default path to library is `/js/lib/iit`, but you can specify your own path
    pathToLibrary: '/path/to/library',
    // To work library need proxy service in your backend.
    // Library send a POST request to proxy service url with address in GET parameter
    // and data string in body. Backend needs to make a request to this address with
    // data string and return received data to the library
    proxyServiceUrl: '/internal-api/proxy',
    // By default library will use Web Workers if supported, but you can force it
    // by setting useMainThread = true
    useMainThread: false,
}

Read private key

Read PK file to get key object with PK content, associated certificates, information about PK and actual certificate.

Parameters:

• keyFile: PK file in Blob format
• password: PK password
• caServerIdx: PK vendor, you can get list of supported CA servers with getCAServers function
• certificateFiles: optional parameter, some CA use certificates from file, so we need to pass PK file and associated certificates file/files. You can use getCAServerSettings function to find out which certificates type are used.

// List of supported CA servers
const caServers = vchasnoSigner.getCAServers();

// CA server settings
const caServerSettings = vchasnoSigner.getCAServerSettings(caServers[idx]);
caServerSettings.loadCertsFromFile;  // true - need to pass associated certificates, false - certificates will be found in CA servers

// Read PK
const key = await vchasnoSigner.readKey(keyFile, password, caServerIdx, certificateFiles);
key.keyData //content of PK
key.password //PK password
key.certificates //PK associated certificates
key.keyInfo //information about PK owner
key.certificateInfo //information about actual associated certificate

Sign data

Sign data with PK, verify signature and return signature object.

Parameters:

• data: data to sign in Blob, ArrayBuffer, or Uint8Array format
• key: key object from readKey function

const eSign = vchasnoSigner.signData(data, key);

Also data can be signed internaly in p7s container

const [eSign, p7s] = vchasnoSigner.signDataInternal(data, key);

Verify signature

Verify association between data and signature, return information about signature.

Parameters:

• data: data to sign in Blob, ArrayBuffer or Uint8Array format
• eSign: signature string from signData function

const signInfo = vchasnoSigner.verifySign(data, eSign);

For internal signatures need to pass only p7s container.

Parameters:

• p7s: p7s container from signDataInternal function

const signInfo = vchasnoSigner.verifySignInternal(p7s);

For library developers

Autodeploy

To deploy new version:

npm version <patch|minor|major>
git push origin --atomic HEAD v0.0.1

Update certificates

• Update CAs.json, CACertificates
  • Docker with just

    # buid container if needed
    just docker-build-image
    # update certificates
    just docker-update-ca-servers
    

  • Node

    wget --output-document ./scripts/rawCAs.json https://iit.com.ua/download/productfiles/CAs.json
    wget --output-document ./src/files/CACertificates.p7b https://iit.com.ua/download/productfiles/CACertificates.p7b
    
    node scripts/generateCAServers.js
    

• Add new tag