@origyn/hsm-identity v1.1.3

Pre-required NitroHsm

OpenSC is a set of software tools and libraries for working with smart cards with a focus on smart cards with cryptographic capabilities. OpenSC simplifies the use of smart cards in security applications such as authentication, encryption, and digital signatures

sudo apt-get update -y
sudo apt-get install -y opensc

After installing the opensc package, the "pkcs11-tool" and "sc-hsm-tool" tools, as well as a file opensc-pkcs11.so which will be required for work.

We also need to initialize the token using sc-hsm-tool, then key pair gen! 1. pkcs11-tool --module opensc-pkcs11.so --init-token --init-pin --so-pin=3537363231383830 --new-pin=648219 --label="HSM" --pin=648219 2. pkcs11-tool --module opensc-pkcs11.so --login --pin 648219 --keypairgen --key-type EC:secp256k1 --label "HSM EC Key"

To familiarization the sc-hsm-tool go here, and pkcs11-tool go here

Environments for NitroHSM!

LIBRARY_PATH => path to opensc-pkcs11.so file
PIN => pin initialize from token 

By default path opensc-pkcs11.so in "ubuntu" /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so

Pre-required SoftHsm

SoftHSM is an implementation of a cryptographic store accessible through a PKCS #11 interface. You can use it to explore PKCS #11 without having a Hardware Security Module. It is being developed as a part of the OpenDNSSEC project. SoftHSM uses Botan for its cryptographic operations.

sudo apt-get update -y
sudo apt-get install -y softhsm2

Whilst initializing token as a non-root user, we invariably try to access the default /etc/softhsm/softhsm2.conf which points tokens to be staged under /var/lib/softhsm/tokens whose ownership/permission is limited to be used by root and its associated groups. Changing ownership/permission of /var/lib/softhsm/tokens doesn't solve the problem as we cannot access /etc/softhsm/softhsm2.conf in the first place given the access limitation, so we should be doing this instead:

• cd $HOME
• mkdir -p $HOME/lib/softhsm/tokens
• cd $HOME/lib/softhsm/
• echo "directories.tokendir = $PWD/tokens" > softhsm2.conf
• export SOFTHSM2_CONF=$HOME/lib/softhsm/softhsm2.conf

The token can be initialized using this command: 1. softhsm2-util --init-token --slot 0 --label "token" 2. After that, are required to enter a pin and so-pin corresponding to the this from the environment variable.

To familiarization the softhsm2-util go here

Environments for SoftHsm!

LIBRARY_PATH => path to libsofthsm2.so file
PIN => pin initialize from token 

By default path libsofthsm2.so in "ubuntu" /usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so

Documentation

SoftHSM2Identity is implemented from SignIdentity which is located in @dfinity/agent

To generate a key pair, Crypto node-webcrypto-p11 is used

SoftHSM2Identity method static create contains the options ISoftHSM2Config and algorithm ISoftHSM2Algorithm required to create an instance identifier.

export interface IHSMConfig {
    name?: string; // this name of PKCS11 module
    slot?: number; // this is the logical section where the token is stored, softhsm2-util --slot <number>  The slot where the token is located
    readWrite?: boolean; // required to configure Crypto from node-webcrypto-p11
    pin?: string; // this is the PIN for the normal user
    extractable?: boolean; // parameter that affects the extraction of keys
}

export interface IHSMAlgorithm {
    name: string; // Name public key algorithm for creating a digital signature; [Supported algorithms](https://www.npmjs.com/package/node-webcrypto-p11)
    namedCurve: string; // The named elliptic curves are over a prime field; Mechanism supports extended list of named curves P-256, P-384, P-521, and K-256;
    hash: string; // The named hashing algorithm; example SHA-256
}

Crypto accepts config which is implemented from CryptoParams

Config Crypto {
  library: string; // Path to the library
  name?: string; // Name of PKCS11 module
  slot?: number; // Index of the slot
  readWrite?: boolean;
  pin: string; // PIN of the slot
}

Methods HSMIdentity

Installation

$ npm i -S @origyn/hsm-identity

Examples

In order to determine which tool to use NitroHSM or SoftHSM, pass the corresponding path to the file opensc-pkcs11.so, libsofthsm2.so to the "library".

You may set LIBRARY_PATH and PIN via env variables or pass them with a config object as shown below. Env variables would be applied by default.

    import { NitroHSMIdentity } from '@origyn/hsm-identity';

const config = {
    library: process.env.LIBRARY_PATH,
    pin: process.env.PIN,
}

const initAlgorithm = {
    name: 'ECDSA',
    namedCurve: 'K-256',
    hash: 'SHA-256',
};

const identity = await NitroHSMIdentity.create(config, initAlgorithm);
console.log(identity.getPublicKey());

import { NitroHSMIdentity } from '@origyn/hsm-identity';

const config = {
    library: process.env.LIBRARY_PATH,
    pin: process.env.PIN,
}

const initAlgorithm = {
    name: 'ECDSA',
    namedCurve: 'K-256',
    hash: 'SHA-256',
};

// Example: ['534d438fd95d04d6a3313efd0e1b8b33']
// To get the keys from the terminal, use `` pkcs11-tool --list-objects ``
const keys = await NitroHSMIdentity.getCryptoKeys(config);
if (!keys.length) {
    throw 'Keys empty, need create crypto key for use import';
}

const identity = await NitroHSMIdentity.import(keys[0], config, initAlgorithm);
console.log(identity.getPublicKey());