README.md

jscu: A Universal Cryptographic Library for JavaScript

--

WARNING: 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.

NOTE: This repository is a monorepo of a universal cryptographic library for JavaScript called js-crypto-utils (jscu), which is designed to work in most modern browsers and Node.js. A detailed explanation would be given in each package repository. The root package is given here (in develop branch).

Terminated to support MS IE11 and released v1.0 (Sep. 30, 2020).

Introduction and overview of this monorepo

This project called jscu is being developed to provide unified cryptographic APIs for browsers and Node.js. There currently exist various sophisticated cryptographic suites for JavaScript that are implemented as native functions, e.g., WebCrypto API and crypto in Node.js. However, they have different interfaces and are NOT supported on all platforms. For instance, FireFox cannot be fed PKCS8-formatted private key in WebCrypto API but Chrome does. On the other hand, such suites have not been designed to keep compatibility with existing non-Web cryptographic suites like OpenSSL. This can be seen from the fact that WebCrypto API does not support PEM-formatted keys. Hence we (actually I!) need to write ugly codes to enable apps to work in various environments. From this observation, we aim that this library provides support functions to fill such gaps among JS cryptographic suites and that between JavaScript and other popular crypto suites.

In particular, this library provides unified APIs of the following cryptographic functions that work in most modern browsers and Node.js.

• ECDSA signing, verification, key generation (P-256/P-384/P-521/P-256K)
• RSA-PSS/RSASSA-PKCS1-v1_5 signing, verification, key generation.
• Encryption using ECDH and HKDF.
• Encryption using RSA-OAEP.
• Public/private key format conversion between JWK and PEM/DER (SPKI for public/PKCS8 for private)
• Generation of JWK Thumbprint
• Generation of X.509 public key certificate from JWK and extraction of JWK public key from X.509 public key certificate.

Additionally, this library provides random, hash, AES, HMAC, HKDF, and PBKDF functions. This implies the jscu is composed of several subpackages and can be seen as a cryptographic suite like openpgpjs. The root package, js-crypto-utils, of the suite and its subpackages are listed as follows.

• crypto-utils: Root cryptographic package providing unified APIs.
• x509-utils: Subpackage handling X509 certificates.
• key-utils: Subpackage handling various key formats like PEM, DER, and JWK.
• ec: Subpackage providing naive encryption and signing of elliptic curve cryptography.
• rsa: Subpackage providing naive encryption and signing of RSA cryptography.
• aes: Subpackage for AES encryption.
• random: Subpackage for the cryptographic random generator.
• hash: Subpackage providing hash functions including SHA-2 and SHA-3.
• hkdf: Subpackage providing hash-based key derivation function.
• pbkdf: Subpackage providing password-based key derivation function 1 and 2.
• hmac: Subpackage providing hash-based message authentication code.

The structure of the package is described in the README.md of the root package, and hence we should start from there. But we can use various cryptographic functions not only via the root package, js-crypto-utils, but also by directly importing subpackages of intended functions. We should refer to README.md of each subpackage for its detailed usage.

For developers and contributors

Using npm package is the simplest way to fully leverage jscu functions. Considering you fork, develop, and update jscu packages themselves, i.e., as developers and contributors, usage of this monorepo and procedures for NPM deployment are summarized as follows.

• This monorepo is managed via Yarn Workspace and Lerna. After cloning this Git repo, just do yarn install at the root of the cloned folder. Then the setup is all done.
• Versioning pattern of each package is completely independent, but the version of this Git repository specified in the root package.json is tied with the root package, i.e., packages/js-crypto-utils. The name of root package is also given in the root package.json.
• Deployment of packages to NPM must be done through CircleCI, and the deployment operation is only triggered by tags associated with Git repo version. Any commits to any branch and any tags of individual package versions won't kick the deployment mechanism. The versioning and tagging would be done through the following combination of GitFlow and Lerna procedures.
  1. First execute yarn flow:version and bump a version of each package that has been modified on develop branch. Here we note that for each updated package, the updated tag would be committed (not pushed), and hence we should almost finalize the release operation at least for each package. This simultaneously update the repo version specified in the root package.json without committing.
  2. Add final changes for release at the level of GitHub repo. Then, commit changes and then execute yarn release:start to start the release process on a release branch. Here we note the release version will be the updated Git repo version.
  3. To finalize the release operation, execute yarn release:finish to merge the release branch to master, and then merge master to develop. It will also tag the master branch with the updated Git repo version, i.e., the root package (packages/js-crypto-utils) version.
  4. Execute yarn release:push and push all branches and the generated tag of Git repo version to GitHub.

Contributing

jscu is free, open-source software licensed under MIT License.

You can open issues for bugs you've found or features you think are missing. You can also submit pull requests to this repository.

Contributors are more than welcome!

Documentation

The jscu documentation is a dynamically generated site from this monorepo via esdoc. You can submit pull requests to 'docs' of this monorepo for document updates.