# Forge
[![npm package](https://nodei.co/npm/node-forge.png?downloads=true&downloadRank=true&stars=true)](https://nodei.co/npm/node-forge/)
[![Build status](https://img.shields.io/travis/digitalbazaar/forge.svg?branch=master)](https://travis-ci.org/digitalbazaar/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](#introduction)
* [Performance](#performance)
* [Installation](#installation)
* [Testing](#testing)
* [Contributing](#contributing)
### API
* [Options](#options)
### Transports
* [TLS](#tls)
* [HTTP](#http)
* [SSH](#ssh)
* [XHR](#xhr)
* [Sockets](#socket)
### Ciphers
* [CIPHER](#cipher)
* [AES](#aes)
* [DES](#des)
* [RC2](#rc2)
### PKI
* [ED25519](#ed25519)
* [RSA](#rsa)
* [RSA-KEM](#rsakem)
* [X.509](#x509)
* [PKCS#5](#pkcs5)
* [PKCS#7](#pkcs7)
* [PKCS#8](#pkcs8)
* [PKCS#10](#pkcs10)
* [PKCS#12](#pkcs12)
* [ASN.1](#asn)
### Message Digests
* [SHA1](#sha1)
* [SHA256](#sha256)
* [SHA384](#sha384)
* [SHA512](#sha512)
* [MD5](#md5)
* [HMAC](#hmac)
### Utilities
* [Prime](#prime)
* [PRNG](#prng)
* [Tasks](#task)
* [Utilities](#util)
* [Logging](#log)
* [Debugging](#debug)
* [Flash Networking Support](#flash)
### Other
* [Security Considerations](#security-considerations)
* [Library Background](#library-background)
* [Contact](#contact)
* [Donations](#donations)
---------------------------------------
Installation
------------
**Note**: Please see the [Security Considerations](#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://npmjs.org/package/node-forge
Installation:
npm install node-forge
You can then use forge as a regular module:
```js
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.
### Bundle / Bower
Each release is published in a separate repository as pre-built and minimized
basic forge bundles using the [UMD][] format.
https://github.com/digitalbazaar/forge-dist
This bundle can be used in many environments. In particular it can be installed
with [Bower][]:
bower install forge
### jsDelivr CDN
To use it via [jsDelivr](https://www.jsdelivr.com/package/npm/node-forge) include this in your html:
```html
<script src="https://cdn.jsdelivr.net/npm/node-forge@0.7.0/dist/forge.min.js"></script>
```
### unpkg CDN
To use it via [unpkg](https://unpkg.com/#/) include this in your html:
```html
<script src="https://unpkg.com/node-forge@0.7.0/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](./flash/README.md) 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:
```html
<script src="YOUR_SCRIPT_PATH/forge.js"></script>
```
or
```html
<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](./webpack.config.js) 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](https://github.com/digitalbazaar/forge/blob/cbebca3780658703d925b61b2caffb1d263a6c1d/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
---
<a name="options" />
### Options
If at any time you wish to disable the use of native code, where available,
for particular forge features like its secure random number generator, you
may set the ```forge.options.usePureJavaScript``` flag to ```true```. It is
not recommended that you set this flag as native code is typically more
performant and may have stronger security properties. It may be useful to
set this flag to test certain features that you plan to run in environments
that are different from your testing environment.
To disable native code when including forge in the browser:
```js
// run this *after* including the forge script
forge.options.usePureJavaScript = true;
```
To disable native code when using Node.js:
```js
var forge = require('node
评论0