PeculiarVentures/pkcs11js PeculiarVentures/pkcs11js

  • Stars
    star
    107
  • Rank 323,587 (Top 7 %)
  • Language
    C++
  • License
    MIT License
  • Created over 8 years ago
  • Updated 5 months ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
PeculiarVentures/pkcs11js
github

PeculiarVentures

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A Node.js implementation of the PKCS#11 2.40 interface

PKCS11js

license test Coverage Status npm version

NPM

PKCS11js is a package for direct interaction with the PKCS#11 API, the standard interface for interacting with hardware crypto devices such as Smart Cards and Hardware Security Modules (HSMs). It was developed to the PKCS#11 2.40 specification and has been tested with a variety of devices.

Versioning Note:

  • Version 1.x was implemented using the nan module, which allowed the package to be built for older versions of Node.js.
  • Starting from version 2.x, the module has been rewritten to use napi. As a result, the minimum required Node.js version is now v18.

For most use cases, we recommend our package Graphene, which provides a simplistic Object Oriented interface for interacting with PKCS#11 devices.

This was developed to the PKCS#11 2.40 specification. It should be easy enough to extend it for any new versions at a later date.

It has been tested with :

NOTE: For testing purposes it may be easier to work with SoftHSM2 which is a software implementation of PKCS#11 based on OpenSSL or Botan.

Installation

$ npm install pkcs11js

Documentation

https://peculiarventures.github.io/pkcs11js/

Install SoftHSM2

Examples

Example #1

var pkcs11js = require("pkcs11js");

var pkcs11 = new pkcs11js.PKCS11();
pkcs11.load("/usr/local/lib/softhsm/libsofthsm2.so");

pkcs11.C_Initialize();

try {
    // Getting info about PKCS11 Module
    var module_info = pkcs11.C_GetInfo();

    // Getting list of slots
    var slots = pkcs11.C_GetSlotList(true);
    var slot = slots[0];

    // Getting info about slot
    var slot_info = pkcs11.C_GetSlotInfo(slot);
    // Getting info about token
    var token_info = pkcs11.C_GetTokenInfo(slot);

    // Getting info about Mechanism
    var mechs = pkcs11.C_GetMechanismList(slot);
    var mech_info = pkcs11.C_GetMechanismInfo(slot, mechs[0]);

    var session = pkcs11.C_OpenSession(slot, pkcs11js.CKF_RW_SESSION | pkcs11js.CKF_SERIAL_SESSION);

    // Getting info about Session
    var info = pkcs11.C_GetSessionInfo(session);
    pkcs11.C_Login(session, 1, "password");

    /**
     * Your app code here
     */
    
    pkcs11.C_Logout(session);
    pkcs11.C_CloseSession(session);
}
catch(e){
    console.error(e);
}
finally {
    pkcs11.C_Finalize();
}

Example #2

Generating secret key using AES mechanism

var template = [
    { type: pkcs11js.CKA_CLASS, value: pkcs11js.CKO_SECRET_KEY },
    { type: pkcs11js.CKA_TOKEN, value: false },
    { type: pkcs11js.CKA_LABEL, value: "My AES Key" },
    { type: pkcs11js.CKA_VALUE_LEN, value: 256 / 8 },
    { type: pkcs11js.CKA_ENCRYPT, value: true },
    { type: pkcs11js.CKA_DECRYPT, value: true },
];
var key = pkcs11.C_GenerateKey(session, { mechanism: pkcs11js.CKM_AES_KEY_GEN }, template);

Example #3

Generating key pair using RSA-PKCS1 mechanism

var publicKeyTemplate = [
    { type: pkcs11js.CKA_CLASS, value: pkcs11js.CKO_PUBLIC_KEY },
    { type: pkcs11js.CKA_TOKEN, value: false },
    { type: pkcs11js.CKA_LABEL, value: "My RSA Public Key" },
    { type: pkcs11js.CKA_PUBLIC_EXPONENT, value: new Buffer([1, 0, 1]) },
    { type: pkcs11js.CKA_MODULUS_BITS, value: 2048 },
    { type: pkcs11js.CKA_VERIFY, value: true }
];
var privateKeyTemplate = [
    { type: pkcs11js.CKA_CLASS, value: pkcs11js.CKO_PRIVATE_KEY },
    { type: pkcs11js.CKA_TOKEN, value: false },
    { type: pkcs11js.CKA_LABEL, value: "My RSA Private Key" },
    { type: pkcs11js.CKA_SIGN, value: true },
];
var keys = pkcs11.C_GenerateKeyPair(session, { mechanism: pkcs11js.CKM_RSA_PKCS_KEY_PAIR_GEN }, publicKeyTemplate, privateKeyTemplate);

Example #4

Generating key pair using ECDSA mechanism

var publicKeyTemplate = [
    { type: pkcs11js.CKA_CLASS, value: pkcs11js.CKO_PUBLIC_KEY },
    { type: pkcs11js.CKA_TOKEN, value: false },
    { type: pkcs11js.CKA_LABEL, value: "My EC Public Key" },
    { type: pkcs11js.CKA_EC_PARAMS, value: new Buffer("06082A8648CE3D030107", "hex") }, // secp256r1
];
var privateKeyTemplate = [
    { type: pkcs11js.CKA_CLASS, value: pkcs11js.CKO_PRIVATE_KEY },
    { type: pkcs11js.CKA_TOKEN, value: false },
    { type: pkcs11js.CKA_LABEL, value: "My EC Private Key" },
    { type: pkcs11js.CKA_DERIVE, value: true },
];
var keys = pkcs11.C_GenerateKeyPair(session, { mechanism: pkcs11js.CKM_EC_KEY_PAIR_GEN }, publicKeyTemplate, privateKeyTemplate);

Example #4

Working with Object

var nObject = pkcs11.C_CreateObject(session, [
    { type: pkcs11js.CKA_CLASS, value: pkcs11js.CKO_DATA },
    { type: pkcs11js.CKA_TOKEN, value: false },
    { type: pkcs11js.CKA_PRIVATE, value: false },
    { type: pkcs11js.CKA_LABEL, value: "My custom data" },
]);

// Updating label of Object
pkcs11.C_SetAttributeValue(session, nObject, [{ type: pkcs11js.CKA_LABEL, value: "My custom data!!!" }]);

// Getting attribute value
var label = pkcs11.C_GetAttributeValue(session, nObject, [
    { type: pkcs11js.CKA_LABEL },
    { type: pkcs11js.CKA_TOKEN }
]);
console.log(label[0].value.toString()); // My custom data!!!
console.log(!!label[1].value[0]); // false

// Copying Object
var cObject = pkcs11.C_CopyObject(session, nObject, [
    { type: pkcs11js.CKA_CLASS},
    { type: pkcs11js.CKA_TOKEN},
    { type: pkcs11js.CKA_PRIVATE},
    { type: pkcs11js.CKA_LABEL},
]);

// Removing Object
pkcs11.C_DestroyObject(session, cObject);

Example #4

Searching objects

NOTE: If template is not set for C_FindObjectsInit, then C_FindObjects returns all objects from slot

pkcs11.C_FindObjectsInit(session, [{ type: pkcs11js.CKA_CLASS, value: pkcs11js.CKO_DATA }]);
var hObject = pkcs11.C_FindObjects(session);
while (hObject) {
    var attrs = pkcs11.C_GetAttributeValue(session, hObject, [
        { type: pkcs11js.CKA_CLASS },
        { type: pkcs11js.CKA_TOKEN },
        { type: pkcs11js.CKA_LABEL }
    ]);
    // Output info for objects from token only
    if (attrs[1].value[0]){
        console.log(`Object #${hObject}: ${attrs[2].value.toString()}`);
    }
    hObject = pkcs11.C_FindObjects(session);
}
pkcs11.C_FindObjectsFinal(session);

Example #5

Generating random values

var random = pkcs11.C_GenerateRandom(session, new Buffer(20));
console.log(random.toString("hex"));

or

var random = new Buffer(20);
pkcs11.C_GenerateRandom(session, random);
console.log(random.toString("hex"));

Example #6

Digest

pkcs11.C_DigestInit(_session, { mechanism: pkcs11js.CKM_SHA256 });

pkcs11.C_DigestUpdate(session, new Buffer("Incoming message 1"));
pkcs11.C_DigestUpdate(session, new Buffer("Incoming message N"));

var digest = pkcs11.C_DigestFinal(_session, Buffer(256 / 8));

console.log(digest.toString("hex"));

Example #7

Signing data

pkcs11.C_SignInit(session, { mechanism: pkcs11js.CKM_SHA256_RSA_PKCS }, keys.privateKey);

pkcs11.C_SignUpdate(session, new Buffer("Incoming message 1"));
pkcs11.C_SignUpdate(session, new Buffer("Incoming message N"));

var signature = pkcs11.C_SignFinal(session, Buffer(256));

Verifying data

pkcs11.C_VerifyInit(session, { mechanism: pkcs11js.CKM_SHA256_RSA_PKCS }, keys.publicKey);

pkcs11.C_VerifyUpdate(session, new Buffer("Incoming message 1"));
pkcs11.C_VerifyUpdate(session, new Buffer("Incoming message N"));

var verify = pkcs11.C_VerifyFinal(session, signature);

Example #8

Encrypting data with AES-CBC mechanism

var cbc_param = pkcs11.C_GenerateRandom(new Buffer(16));

pkcs11.C_EncryptInit(
    session,
    {
        mechanism: pkcs11js.CKM_AES_CBC,
        parameter: cbc_param
    },
    secretKey
);

var enc = new Buffer(0);
enc = Buffer.concat([enc, pkcs11.C_EncryptUpdate(session, new Buffer("Incoming data 1"), new Buffer(16))]);
enc = Buffer.concat([enc, pkcs11.C_EncryptUpdate(session, new Buffer("Incoming data N"), new Buffer(16))]);
enc = Buffer.concat([enc, pkcs11.C_EncryptFinal(session, new Buffer(16))]);

console.log(enc.toString("hex"));

Decrypting data with AES-CBC mechanism

pkcs11.C_DecryptInit(
    session,
    {
        mechanism: pkcs11js.CKM_AES_CBC,
        parameter: cbc_param
    },
    secretKey
);

var dec = new Buffer(0);
dec = Buffer.concat([dec, pkcs11.C_DecryptUpdate(session, enc, new Buffer(32))]);
dec = Buffer.concat([dec, pkcs11.C_DecryptFinal(session, new Buffer(16))]);

console.log(dec.toString());

Example #9

Deriving key with ECDH mechanism

// Receive public data from EC public key
var attrs = pkcs11.C_GetAttributeValue(session, publicKeyEC, [{ type: pkcs11js.CKA_EC_POINT }])
var ec = attrs[0].value;

var derivedKey = pkcs11.C_DeriveKey(
    session,
    {
        mechanism: pkcs11js.CKM_ECDH1_DERIVE,
        parameter: {
            type: pkcs11js.CK_PARAMS_EC_DH,
            kdf: 2,
            publicData: ec
        }
    },
    privateKeyEC,
    [
        { type: pkcs11js.CKA_CLASS, value: pkcs11js.CKO_SECRET_KEY },
        { type: pkcs11js.CKA_TOKEN, value: false },
        { type: pkcs11js.CKA_KEY_TYPE, value: pkcs11js.CKK_AES },
        { type: pkcs11js.CKA_LABEL, value: "Derived AES key" },
        { type: pkcs11js.CKA_ENCRYPT, value: true },
        { type: pkcs11js.CKA_VALUE_LEN, value: 256 / 8 }
    ]
);

Example #10

Initializing NSS crypto library

Use options parameter for C_Initialize function.

Type

interface InitializationOptions {
    /**
     * NSS library parameters
     */
    libraryParameters?: string;
    /**
     * bit flags specifying options for `C_Initialize`
     * - CKF_LIBRARY_CANT_CREATE_OS_THREADS. True if application threads which are executing calls to the library
     *   may not use native operating system calls to spawn new threads; false if they may
     * - CKF_OS_LOCKING_OK. True if the library can use the native operation system threading model for locking;
     *   false otherwise
     */
    flags?: number;
}
/**
 * Initializes the Cryptoki library
 * @param options Initialization options
 * Supports implementation of standard `CK_C_INITIALIZE_ARGS` and extended NSS format.
 * - if `options` is null or empty, it calls native `C_Initialize` with `NULL`
 * - if `options` doesn't have `libraryParameters`, it uses `CK_C_INITIALIZE_ARGS` structure
 * - if `options` has `libraryParameters`, it uses extended NSS structure
 */
C_Initialize(options?: InitializationOptions): void;

Code

const mod = new pkcs11.PKCS11();
mod.load("/usr/local/opt/nss/lib/libsoftokn3.dylib");

mod.C_Initialize({
    libraryParameters: "configdir='' certPrefix='' keyPrefix='' secmod='' flags=readOnly,noCertDB,noModDB,forceOpen,optimizeSpace",
});

// Your code here

mod.C_Finalize();

More info about NSS params for C_Initialize

Example #11

Detect a slot event

var pkcs11js = require("pkcs11js");
var pkcs11 = new pkcs11js.PKCS11();
// Need a compliant Cryptoki Version 2.01 or later
pkcs11.load("/usr/local/lib/softhsm/libsofthsm2.so");

pkcs11.C_Initialize();

try {
    const slotId = pkcs11.C_WaitForSlotEvent(pkcs11js.CKF_DONT_BLOCK);
    if (slotId) {
        console.log(`Slot ${slotId} has been inserted`);
    } else {
        console.log(`No slot event`);
    }
} catch (e) {
    console.error(e);
} finally {
    pkcs11.C_Finalize();
}

Suitability

At this time this solution should be considered suitable for research and experimentation, further code and security review is needed before utilization in a production application.

Bug Reporting

Please report bugs either as pull requests or as issues in the issue tracker. Graphene has a full disclosure vulnerability policy. Please do NOT attempt to report any security vulnerability in this code privately to anybody.

Related

More Repositories

1

PKI.js

PKI.js is a pure JavaScript library implementing the formats that are used in PKI applications (signing, encryption, certificate requests, OCSP and TSP requests/responses). It is built on WebCrypto (Web Cryptography API) and requires no plug-ins.
TypeScript
1,300
star
2

ASN1.js

ASN1js is a pure JavaScript library implementing a full ASN.1 BER decoder and encoder.
TypeScript
267
star
3

webcrypto

A WebCrypto Polyfill for NodeJS
TypeScript
183
star
4

GammaCV

GammaCV is a WebGL accelerated Computer Vision library for browser
JavaScript
175
star
5

graphene

A simple layer for interacting with PKCS #11 / PKCS11 / CryptoKI for Node in TypeScript. (Keywords: Javascript, PKCS#11, Crypto, Smart Card, HSM)
TypeScript
162
star
6

webcrypto-liner

webcrypto-liner is a polyfill that let's down-level User Agents (like IE/Edge) use libraries that depend on WebCrypto. (Keywords: Javascript, WebCrypto, Shim, Polyfill)
TypeScript
149
star
7

js-zxing-pdf417

Javascript port of the PDF417 detector and decoder from http://github.com/zxing/zxing (Keywords: Barcode, PDF 417, Javascript)
JavaScript
142
star
8

xadesjs

A pure Typescript/Javascript implementation of XAdES based on XMLDSIGjs. (Keywords: WebCrypto, XMLDSIG, XADES, eIDAS, Trust List, X.509, CRL, OCSP)
TypeScript
140
star
9

node-webcrypto-ossl

A WebCrypto Polyfill for Node in TypeScript built on OpenSSL.
C++
128
star
10

fortify

Fortify enables web applications to use smart cards, local certificate stores and do certificate enrollment. This is the desktop application repository.
TypeScript
114
star
11

2key-ratchet

2key-ratchet is an implementation of a Double Ratchet protocol and X3DH in TypeScript utilizing WebCrypto.
TypeScript
109
star
12

x509

@peculiar/x509 is an easy to use TypeScript/Javascript library based on @peculiar/asn1-schema that makes generating X.509 Certificates and Certificate Requests as well as validating certificate chains easy
TypeScript
81
star
13

pv-certificates-viewer

Web components for viewing lists of certificates and certificates
TypeScript
61
star
14

xmldsigjs

XMLDSIGjs provides an implementation of XMLDSIG in Typescript/Javascript based on WebCrypto
TypeScript
45
star
15

node-webcrypto-p11

A WebCrypto Polyfill for Node in typescript built on PKCS#11.
TypeScript
43
star
16

asn1-schema

asn1-schema is a collection of TypeScript schemas that make working with common ASN.1 objects easy
TypeScript
33
star
17

tl-create

tl-create is a cross-platform command line tool to create a X.509 trust list from various trust stores. (Keywords: CABFORUM, eIDAS, WebPKI)
HTML
33
star
18

pvpkcs11

pvpkcs11 consists of a input validation library and a set of PKCS#11 implementations that wrap operating system and browser cryptographic implementations.
C++
32
star
19

csrhelp

csrhelp.peculiarventures.com - A site that helps users generate SSL certificate requests (Keywords: WebCrypto, PKIjs, PKCS#10, CSR)
JavaScript
27
star
20

webcrypto-core

A input validation layer for WebCrypto polyfills.
TypeScript
27
star
21

tsprotobuf

tsprotobuf is a helper library that contains functions that make working with ProtoBuf easier in Typescript.
TypeScript
21
star
22

xml-core

xml-core is a set of classes that make it easier to work with XML within the browser and node.
TypeScript
19
star
23

CAdES.js

CAdESjs is an implementation of CAdES (CMS Advanced Electronic Signatures)in pure Javascript.
JavaScript
18
star
24

webcrypto-local

webcrypto-local is a cross platform service that provides access to PKCS#11 implementations over a protocol we call webcrypto-socket.
TypeScript
18
star
25

fortify-tools

Fortify enables web applications to use smart cards, local certificate stores and do certificate enrollment. This is the "Tool" application used in the Fortify desktop application.
JavaScript
15
star
26

ByteStream.js

ByteStream.js is a set of classes manipulating bytes and bits with optimized for speed perfomance
TypeScript
13
star
27

acme-ts

Provides client and server implementations of ACME (RFC 8555) in TypeScript. It enables you to build solutions that provide complete and robust certificate lifecycle management.
TypeScript
12
star
28

fortify-examples

Fortify enables web applications to use smart cards, local certificate stores and do certificate enrollment. This is a set of examples of how to use Fortify in your own applications.
JavaScript
8
star
29

pvutils

pvutils is a set of common utility functions used in various Peculiar Ventures Javascript based projects.
TypeScript
7
star
30

acme-cs

Provides client and server implementations of ACME (RFC 8555) in C-Sharp. It enables you to build solutions that provide complete and robust certificate lifecycle management.
C#
6
star
31

graphene-cli

The graphene-cli is a cross-platform command line tool for working with PKCS#11 devices
TypeScript
5
star
32

webcrypto-docs

5
star
33

pv-webcrypto-tests

A basic test suite for WebCrypto.
JavaScript
5
star
34

PVCertViewer

Example certificate viewer based on PKIjs
JavaScript
5
star
35

webcrypto.dev-examples

Peculiar Ventures' webcrypto.dev is a collection of cryptography and X.509 certificate libraries, making it easier for developers to integrate these technologies into their projects.
TypeScript
4
star
36

json-schema

This package uses ES2015 decorators to simplify JSON schema creation and use
TypeScript
3
star
37

pvtsutils

pvtsutils is a set of common utility functions used in various Peculiar Ventures TypeScript based projects.
TypeScript
3
star
38

validatewallet.com

validatewallet.com website
HTML
2
star
39

Font.js

FontJS (Font.js) is a packages for TrueType font parsing and manipulation
TypeScript
2
star
40

peculiar-react-components

JavaScript
2
star
41

validatewallet

HTML
1
star
42

ExamplePDFs

1
star
43

pkcs11test

Simple CLI application for PKCS#11 testing based on WebCrypto library
TypeScript
1
star
44

peculiar-ui

TypeScript
1
star