forge

Forge

A native implementation of [TLS][] (and various other cryptographic tools) in [JavaScript][].

Introduction

The Forge software is a fully native implementation of the [TLS][] protocol in JavaScript, a set of cryptography utilities, and a set of tools for developing Web Apps that utilize many network resources.

Performance

Forge is fast. Benchmarks against other popular JavaScript cryptography libraries can be found here:

• http://dominictarr.github.io/crypto-bench/
• http://cryptojs.altervista.org/test/simulate-threading-speed_test.html

Documentation

• Introduction
• Performance
• Installation
• Testing
• Contributing

API

• Options

Transports

• TLS
• HTTP
• SSH
• XHR
• Sockets

Ciphers

• CIPHER
• AES
• DES
• RC2

PKI

• ED25519
• RSA
• RSA-KEM
• X.509
• PKCS#5
• PKCS#7
• PKCS#8
• PKCS#10
• PKCS#12
• ASN.1

Message Digests

• SHA1
• SHA256
• SHA384
• SHA512
• MD5
• HMAC

Utilities

• Prime
• PRNG
• Tasks
• Utilities
• Logging
• Flash Networking Support

Other

• Security Considerations
• Library Background
• Contact
• Donations

Installation

Note: Please see the Security Considerations section before using packaging systems and pre-built files.

Forge uses a [CommonJS][] module structure with a build process for browser bundles. The older [0.6.x][] branch with standalone files is available but will not be regularly updated.

Node.js

If you want to use forge with [Node.js][], it is available through npm:

https://www.npmjs.com/package/node-forge

Installation:

npm install node-forge

You can then use forge as a regular module:

var forge = require('node-forge');

The npm package includes pre-built forge.min.js, forge.all.min.js, and prime.worker.min.js using the [UMD][] format.

jsDelivr CDN

To use it via jsDelivr include this in your html:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/forge.min.js"></script>

unpkg CDN

To use it via unpkg include this in your html:

<script src="https://unpkg.com/[email protected]/dist/forge.min.js"></script>

Development Requirements

The core JavaScript has the following requirements to build and test:

• Building a browser bundle:
  • Node.js
  • npm
• Testing
  • Node.js
  • npm
  • Chrome, Firefox, Safari (optional)

Some special networking features can optionally use a Flash component. See the Flash README for details.

Building for a web browser

To create single file bundles for use with browsers run the following:

npm install
npm run build

This will create single non-minimized and minimized files that can be included in the browser:

dist/forge.js
dist/forge.min.js

A bundle that adds some utilities and networking support is also available:

dist/forge.all.js
dist/forge.all.min.js

Include the file via:

<script src="YOUR_SCRIPT_PATH/forge.js"></script>

or

<script src="YOUR_SCRIPT_PATH/forge.min.js"></script>

The above bundles will synchronously create a global 'forge' object.

Note: These bundles will not include any WebWorker scripts (eg: dist/prime.worker.js), so these will need to be accessible from the browser if any WebWorkers are used.

Building a custom browser bundle

The build process uses [webpack][] and the config file can be modified to generate a file or files that only contain the parts of forge you need.

[Browserify][] override support is also present in package.json.

Testing

Prepare to run tests

npm install

Running automated tests with Node.js

Forge natively runs in a [Node.js][] environment:

npm test

Running automated tests with Headless Chrome

Automated testing is done via [Karma][]. By default it will run the tests with Headless Chrome.

npm run test-karma

Is 'mocha' reporter output too verbose? Other reporters are available. Try 'dots', 'progress', or 'tap'.

npm run test-karma -- --reporters progress

By default [webpack][] is used. [Browserify][] can also be used.

BUNDLER=browserify npm run test-karma

Running automated tests with one or more browsers

You can also specify one or more browsers to use.

npm run test-karma -- --browsers Chrome,Firefox,Safari,ChromeHeadless

The reporter option and BUNDLER environment variable can also be used.

Running manual tests in a browser

Testing in a browser uses [webpack][] to combine forge and all tests and then loading the result in a browser. A simple web server is provided that will output the HTTP or HTTPS URLs to load. It also will start a simple Flash Policy Server. Unit tests and older legacy tests are provided. Custom ports can be used by running node tests/server.js manually.

To run the unit tests in a browser a special forge build is required:

npm run test-build

To run legacy browser based tests the main forge build is required:

npm run build

The tests are run with a custom server that prints out the URLs to use:

npm run test-server

Running other tests

There are some other random tests and benchmarks available in the tests directory.

Coverage testing

To perform coverage testing of the unit tests, run the following. The results will be put in the coverage/ directory. Note that coverage testing can slow down some tests considerably.

npm install
npm run coverage

Contributing

Any contributions (eg: PRs) that are accepted will be brought under the same license used by the rest of the Forge project. This license allows Forge to be used under the terms of either the BSD License or the GNU General Public License (GPL) Version 2.

See: LICENSE

If a contribution contains 3rd party source code with its own license, it may retain it, so long as that license is compatible with the Forge license.

API

// run this *after* including the forge script
forge.options.usePureJavaScript = true;

var forge = require('node-forge');
forge.options.usePureJavaScript = true;

…

…

…

// encodes (and optionally encrypts) a private RSA key as a Putty PPK file
forge.ssh.privateKeyToPutty(privateKey, passphrase, comment);

// encodes a public RSA key as an OpenSSH file
forge.ssh.publicKeyToOpenSSH(key, comment);

// encodes a private RSA key as an OpenSSH file
forge.ssh.privateKeyToOpenSSH(privateKey, passphrase);

// gets the SSH public key fingerprint in a byte buffer
forge.ssh.getPublicKeyFingerprint(key);

// gets a hex-encoded, colon-delimited SSH public key fingerprint
forge.ssh.getPublicKeyFingerprint(key, {encoding: 'hex', delimiter: ':'});

// TODO

// TODO

…

Using forge in Node.js to match openssl's "enc" command line tool (Note: OpenSSL "enc" uses a non-standard file format with a custom key derivation function and a fixed iteration count of 1, which some consider less secure than alternatives such as OpenPGP/GnuPG):

…

Provides [AES][] encryption and decryption in [CBC][], [CFB][], [OFB][], [CTR][], and [GCM][] modes. See CIPHER for examples.

Provides [3DES][] and [DES][] encryption and decryption in [ECB][] and [CBC][] modes. See CIPHER for examples.

// generate a random key and IV
var key = forge.random.getBytesSync(16);
var iv = forge.random.getBytesSync(8);

// encrypt some bytes
var cipher = forge.rc2.createEncryptionCipher(key);
cipher.start(iv);
cipher.update(forge.util.createBuffer(someBytes));
cipher.finish();
var encrypted = cipher.output;
// outputs encrypted hex
console.log(encrypted.toHex());

// decrypt some bytes
var cipher = forge.rc2.createDecryptionCipher(key);
cipher.start(iv);
cipher.update(encrypted);
cipher.finish();
// outputs decrypted hex
console.log(cipher.output.toHex());

…

…

…

…

// generate a password-based 16-byte key
// note an optional message digest can be passed as the final parameter
var salt = forge.random.getBytesSync(128);
var derivedKey = forge.pkcs5.pbkdf2('password', salt, numIterations, 16);

// generate key asynchronously
// note an optional message digest can be passed before the callback
forge.pkcs5.pbkdf2('password', salt, numIterations, 16, function(err, derivedKey) {
  // do something w/derivedKey
});

…