forked from projectmoon/tenebrous-dicebot
2100 lines
59 KiB
Markdown
2100 lines
59 KiB
Markdown
# Forge
|
|
|
|
[](https://nodei.co/npm/node-forge/)
|
|
|
|
[](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-forge');
|
|
forge.options.usePureJavaScript = true;
|
|
```
|
|
|
|
Transports
|
|
----------
|
|
|
|
<a name="tls" />
|
|
|
|
### TLS
|
|
|
|
Provides a native javascript client and server-side [TLS][] implementation.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
// create TLS client
|
|
var client = forge.tls.createConnection({
|
|
server: false,
|
|
caStore: /* Array of PEM-formatted certs or a CA store object */,
|
|
sessionCache: {},
|
|
// supported cipher suites in order of preference
|
|
cipherSuites: [
|
|
forge.tls.CipherSuites.TLS_RSA_WITH_AES_128_CBC_SHA,
|
|
forge.tls.CipherSuites.TLS_RSA_WITH_AES_256_CBC_SHA],
|
|
virtualHost: 'example.com',
|
|
verify: function(connection, verified, depth, certs) {
|
|
if(depth === 0) {
|
|
var cn = certs[0].subject.getField('CN').value;
|
|
if(cn !== 'example.com') {
|
|
verified = {
|
|
alert: forge.tls.Alert.Description.bad_certificate,
|
|
message: 'Certificate common name does not match hostname.'
|
|
};
|
|
}
|
|
}
|
|
return verified;
|
|
},
|
|
connected: function(connection) {
|
|
console.log('connected');
|
|
// send message to server
|
|
connection.prepare(forge.util.encodeUtf8('Hi server!'));
|
|
/* NOTE: experimental, start heartbeat retransmission timer
|
|
myHeartbeatTimer = setInterval(function() {
|
|
connection.prepareHeartbeatRequest(forge.util.createBuffer('1234'));
|
|
}, 5*60*1000);*/
|
|
},
|
|
/* provide a client-side cert if you want
|
|
getCertificate: function(connection, hint) {
|
|
return myClientCertificate;
|
|
},
|
|
/* the private key for the client-side cert if provided */
|
|
getPrivateKey: function(connection, cert) {
|
|
return myClientPrivateKey;
|
|
},
|
|
tlsDataReady: function(connection) {
|
|
// TLS data (encrypted) is ready to be sent to the server
|
|
sendToServerSomehow(connection.tlsData.getBytes());
|
|
// if you were communicating with the server below, you'd do:
|
|
// server.process(connection.tlsData.getBytes());
|
|
},
|
|
dataReady: function(connection) {
|
|
// clear data from the server is ready
|
|
console.log('the server sent: ' +
|
|
forge.util.decodeUtf8(connection.data.getBytes()));
|
|
// close connection
|
|
connection.close();
|
|
},
|
|
/* NOTE: experimental
|
|
heartbeatReceived: function(connection, payload) {
|
|
// restart retransmission timer, look at payload
|
|
clearInterval(myHeartbeatTimer);
|
|
myHeartbeatTimer = setInterval(function() {
|
|
connection.prepareHeartbeatRequest(forge.util.createBuffer('1234'));
|
|
}, 5*60*1000);
|
|
payload.getBytes();
|
|
},*/
|
|
closed: function(connection) {
|
|
console.log('disconnected');
|
|
},
|
|
error: function(connection, error) {
|
|
console.log('uh oh', error);
|
|
}
|
|
});
|
|
|
|
// start the handshake process
|
|
client.handshake();
|
|
|
|
// when encrypted TLS data is received from the server, process it
|
|
client.process(encryptedBytesFromServer);
|
|
|
|
// create TLS server
|
|
var server = forge.tls.createConnection({
|
|
server: true,
|
|
caStore: /* Array of PEM-formatted certs or a CA store object */,
|
|
sessionCache: {},
|
|
// supported cipher suites in order of preference
|
|
cipherSuites: [
|
|
forge.tls.CipherSuites.TLS_RSA_WITH_AES_128_CBC_SHA,
|
|
forge.tls.CipherSuites.TLS_RSA_WITH_AES_256_CBC_SHA],
|
|
// require a client-side certificate if you want
|
|
verifyClient: true,
|
|
verify: function(connection, verified, depth, certs) {
|
|
if(depth === 0) {
|
|
var cn = certs[0].subject.getField('CN').value;
|
|
if(cn !== 'the-client') {
|
|
verified = {
|
|
alert: forge.tls.Alert.Description.bad_certificate,
|
|
message: 'Certificate common name does not match expected client.'
|
|
};
|
|
}
|
|
}
|
|
return verified;
|
|
},
|
|
connected: function(connection) {
|
|
console.log('connected');
|
|
// send message to client
|
|
connection.prepare(forge.util.encodeUtf8('Hi client!'));
|
|
/* NOTE: experimental, start heartbeat retransmission timer
|
|
myHeartbeatTimer = setInterval(function() {
|
|
connection.prepareHeartbeatRequest(forge.util.createBuffer('1234'));
|
|
}, 5*60*1000);*/
|
|
},
|
|
getCertificate: function(connection, hint) {
|
|
return myServerCertificate;
|
|
},
|
|
getPrivateKey: function(connection, cert) {
|
|
return myServerPrivateKey;
|
|
},
|
|
tlsDataReady: function(connection) {
|
|
// TLS data (encrypted) is ready to be sent to the client
|
|
sendToClientSomehow(connection.tlsData.getBytes());
|
|
// if you were communicating with the client above you'd do:
|
|
// client.process(connection.tlsData.getBytes());
|
|
},
|
|
dataReady: function(connection) {
|
|
// clear data from the client is ready
|
|
console.log('the client sent: ' +
|
|
forge.util.decodeUtf8(connection.data.getBytes()));
|
|
// close connection
|
|
connection.close();
|
|
},
|
|
/* NOTE: experimental
|
|
heartbeatReceived: function(connection, payload) {
|
|
// restart retransmission timer, look at payload
|
|
clearInterval(myHeartbeatTimer);
|
|
myHeartbeatTimer = setInterval(function() {
|
|
connection.prepareHeartbeatRequest(forge.util.createBuffer('1234'));
|
|
}, 5*60*1000);
|
|
payload.getBytes();
|
|
},*/
|
|
closed: function(connection) {
|
|
console.log('disconnected');
|
|
},
|
|
error: function(connection, error) {
|
|
console.log('uh oh', error);
|
|
}
|
|
});
|
|
|
|
// when encrypted TLS data is received from the client, process it
|
|
server.process(encryptedBytesFromClient);
|
|
```
|
|
|
|
Connect to a TLS server using node's net.Socket:
|
|
|
|
```js
|
|
var socket = new net.Socket();
|
|
|
|
var client = forge.tls.createConnection({
|
|
server: false,
|
|
verify: function(connection, verified, depth, certs) {
|
|
// skip verification for testing
|
|
console.log('[tls] server certificate verified');
|
|
return true;
|
|
},
|
|
connected: function(connection) {
|
|
console.log('[tls] connected');
|
|
// prepare some data to send (note that the string is interpreted as
|
|
// 'binary' encoded, which works for HTTP which only uses ASCII, use
|
|
// forge.util.encodeUtf8(str) otherwise
|
|
client.prepare('GET / HTTP/1.0\r\n\r\n');
|
|
},
|
|
tlsDataReady: function(connection) {
|
|
// encrypted data is ready to be sent to the server
|
|
var data = connection.tlsData.getBytes();
|
|
socket.write(data, 'binary'); // encoding should be 'binary'
|
|
},
|
|
dataReady: function(connection) {
|
|
// clear data from the server is ready
|
|
var data = connection.data.getBytes();
|
|
console.log('[tls] data received from the server: ' + data);
|
|
},
|
|
closed: function() {
|
|
console.log('[tls] disconnected');
|
|
},
|
|
error: function(connection, error) {
|
|
console.log('[tls] error', error);
|
|
}
|
|
});
|
|
|
|
socket.on('connect', function() {
|
|
console.log('[socket] connected');
|
|
client.handshake();
|
|
});
|
|
socket.on('data', function(data) {
|
|
client.process(data.toString('binary')); // encoding should be 'binary'
|
|
});
|
|
socket.on('end', function() {
|
|
console.log('[socket] disconnected');
|
|
});
|
|
|
|
// connect to google.com
|
|
socket.connect(443, 'google.com');
|
|
|
|
// or connect to gmail's imap server (but don't send the HTTP header above)
|
|
//socket.connect(993, 'imap.gmail.com');
|
|
```
|
|
|
|
<a name="http" />
|
|
|
|
### HTTP
|
|
|
|
Provides a native [JavaScript][] mini-implementation of an http client that
|
|
uses pooled sockets.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
// create an HTTP GET request
|
|
var request = forge.http.createRequest({method: 'GET', path: url.path});
|
|
|
|
// send the request somewhere
|
|
sendSomehow(request.toString());
|
|
|
|
// receive response
|
|
var buffer = forge.util.createBuffer();
|
|
var response = forge.http.createResponse();
|
|
var someAsyncDataHandler = function(bytes) {
|
|
if(!response.bodyReceived) {
|
|
buffer.putBytes(bytes);
|
|
if(!response.headerReceived) {
|
|
if(response.readHeader(buffer)) {
|
|
console.log('HTTP response header: ' + response.toString());
|
|
}
|
|
}
|
|
if(response.headerReceived && !response.bodyReceived) {
|
|
if(response.readBody(buffer)) {
|
|
console.log('HTTP response body: ' + response.body);
|
|
}
|
|
}
|
|
}
|
|
};
|
|
```
|
|
|
|
<a name="ssh" />
|
|
|
|
### SSH
|
|
|
|
Provides some SSH utility functions.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
// 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: ':'});
|
|
```
|
|
|
|
<a name="xhr" />
|
|
|
|
### XHR
|
|
|
|
Provides an XmlHttpRequest implementation using forge.http as a backend.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
// TODO
|
|
```
|
|
|
|
<a name="socket" />
|
|
|
|
### Sockets
|
|
|
|
Provides an interface to create and use raw sockets provided via Flash.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
// TODO
|
|
```
|
|
|
|
Ciphers
|
|
-------
|
|
|
|
<a name="cipher" />
|
|
|
|
### CIPHER
|
|
|
|
Provides a basic API for block encryption and decryption. There is built-in
|
|
support for the ciphers: [AES][], [3DES][], and [DES][], and for the modes
|
|
of operation: [ECB][], [CBC][], [CFB][], [OFB][], [CTR][], and [GCM][].
|
|
|
|
These algorithms are currently supported:
|
|
|
|
* AES-ECB
|
|
* AES-CBC
|
|
* AES-CFB
|
|
* AES-OFB
|
|
* AES-CTR
|
|
* AES-GCM
|
|
* 3DES-ECB
|
|
* 3DES-CBC
|
|
* DES-ECB
|
|
* DES-CBC
|
|
|
|
When using an [AES][] algorithm, the key size will determine whether
|
|
AES-128, AES-192, or AES-256 is used (all are supported). When a [DES][]
|
|
algorithm is used, the key size will determine whether [3DES][] or regular
|
|
[DES][] is used. Use a [3DES][] algorithm to enforce Triple-DES.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
// generate a random key and IV
|
|
// Note: a key size of 16 bytes will use AES-128, 24 => AES-192, 32 => AES-256
|
|
var key = forge.random.getBytesSync(16);
|
|
var iv = forge.random.getBytesSync(16);
|
|
|
|
/* alternatively, generate a password-based 16-byte key
|
|
var salt = forge.random.getBytesSync(128);
|
|
var key = forge.pkcs5.pbkdf2('password', salt, numIterations, 16);
|
|
*/
|
|
|
|
// encrypt some bytes using CBC mode
|
|
// (other modes include: ECB, CFB, OFB, CTR, and GCM)
|
|
// Note: CBC and ECB modes use PKCS#7 padding as default
|
|
var cipher = forge.cipher.createCipher('AES-CBC', key);
|
|
cipher.start({iv: iv});
|
|
cipher.update(forge.util.createBuffer(someBytes));
|
|
cipher.finish();
|
|
var encrypted = cipher.output;
|
|
// outputs encrypted hex
|
|
console.log(encrypted.toHex());
|
|
|
|
// decrypt some bytes using CBC mode
|
|
// (other modes include: CFB, OFB, CTR, and GCM)
|
|
var decipher = forge.cipher.createDecipher('AES-CBC', key);
|
|
decipher.start({iv: iv});
|
|
decipher.update(encrypted);
|
|
var result = decipher.finish(); // check 'result' for true/false
|
|
// outputs decrypted hex
|
|
console.log(decipher.output.toHex());
|
|
|
|
// decrypt bytes using CBC mode and streaming
|
|
// Performance can suffer for large multi-MB inputs due to buffer
|
|
// manipulations. Stream processing in chunks can offer significant
|
|
// improvement. CPU intensive update() calls could also be performed with
|
|
// setImmediate/setTimeout to avoid blocking the main browser UI thread (not
|
|
// shown here). Optimal block size depends on the JavaScript VM and other
|
|
// factors. Encryption can use a simple technique for increased performance.
|
|
var encryptedBytes = encrypted.bytes();
|
|
var decipher = forge.cipher.createDecipher('AES-CBC', key);
|
|
decipher.start({iv: iv});
|
|
var length = encryptedBytes.length;
|
|
var chunkSize = 1024 * 64;
|
|
var index = 0;
|
|
var decrypted = '';
|
|
do {
|
|
decrypted += decipher.output.getBytes();
|
|
var buf = forge.util.createBuffer(encryptedBytes.substr(index, chunkSize));
|
|
decipher.update(buf);
|
|
index += chunkSize;
|
|
} while(index < length);
|
|
var result = decipher.finish();
|
|
assert(result);
|
|
decrypted += decipher.output.getBytes();
|
|
console.log(forge.util.bytesToHex(decrypted));
|
|
|
|
// encrypt some bytes using GCM mode
|
|
var cipher = forge.cipher.createCipher('AES-GCM', key);
|
|
cipher.start({
|
|
iv: iv, // should be a 12-byte binary-encoded string or byte buffer
|
|
additionalData: 'binary-encoded string', // optional
|
|
tagLength: 128 // optional, defaults to 128 bits
|
|
});
|
|
cipher.update(forge.util.createBuffer(someBytes));
|
|
cipher.finish();
|
|
var encrypted = cipher.output;
|
|
var tag = cipher.mode.tag;
|
|
// outputs encrypted hex
|
|
console.log(encrypted.toHex());
|
|
// outputs authentication tag
|
|
console.log(tag.toHex());
|
|
|
|
// decrypt some bytes using GCM mode
|
|
var decipher = forge.cipher.createDecipher('AES-GCM', key);
|
|
decipher.start({
|
|
iv: iv,
|
|
additionalData: 'binary-encoded string', // optional
|
|
tagLength: 128, // optional, defaults to 128 bits
|
|
tag: tag // authentication tag from encryption
|
|
});
|
|
decipher.update(encrypted);
|
|
var pass = decipher.finish();
|
|
// pass is false if there was a failure (eg: authentication tag didn't match)
|
|
if(pass) {
|
|
// outputs decrypted hex
|
|
console.log(decipher.output.toHex());
|
|
}
|
|
```
|
|
|
|
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](https://tools.ietf.org/html/rfc4880)/[GnuPG](https://www.gnupg.org/)):
|
|
|
|
```js
|
|
var forge = require('node-forge');
|
|
var fs = require('fs');
|
|
|
|
// openssl enc -des3 -in input.txt -out input.enc
|
|
function encrypt(password) {
|
|
var input = fs.readFileSync('input.txt', {encoding: 'binary'});
|
|
|
|
// 3DES key and IV sizes
|
|
var keySize = 24;
|
|
var ivSize = 8;
|
|
|
|
// get derived bytes
|
|
// Notes:
|
|
// 1. If using an alternative hash (eg: "-md sha1") pass
|
|
// "forge.md.sha1.create()" as the final parameter.
|
|
// 2. If using "-nosalt", set salt to null.
|
|
var salt = forge.random.getBytesSync(8);
|
|
// var md = forge.md.sha1.create(); // "-md sha1"
|
|
var derivedBytes = forge.pbe.opensslDeriveBytes(
|
|
password, salt, keySize + ivSize/*, md*/);
|
|
var buffer = forge.util.createBuffer(derivedBytes);
|
|
var key = buffer.getBytes(keySize);
|
|
var iv = buffer.getBytes(ivSize);
|
|
|
|
var cipher = forge.cipher.createCipher('3DES-CBC', key);
|
|
cipher.start({iv: iv});
|
|
cipher.update(forge.util.createBuffer(input, 'binary'));
|
|
cipher.finish();
|
|
|
|
var output = forge.util.createBuffer();
|
|
|
|
// if using a salt, prepend this to the output:
|
|
if(salt !== null) {
|
|
output.putBytes('Salted__'); // (add to match openssl tool output)
|
|
output.putBytes(salt);
|
|
}
|
|
output.putBuffer(cipher.output);
|
|
|
|
fs.writeFileSync('input.enc', output.getBytes(), {encoding: 'binary'});
|
|
}
|
|
|
|
// openssl enc -d -des3 -in input.enc -out input.dec.txt
|
|
function decrypt(password) {
|
|
var input = fs.readFileSync('input.enc', {encoding: 'binary'});
|
|
|
|
// parse salt from input
|
|
input = forge.util.createBuffer(input, 'binary');
|
|
// skip "Salted__" (if known to be present)
|
|
input.getBytes('Salted__'.length);
|
|
// read 8-byte salt
|
|
var salt = input.getBytes(8);
|
|
|
|
// Note: if using "-nosalt", skip above parsing and use
|
|
// var salt = null;
|
|
|
|
// 3DES key and IV sizes
|
|
var keySize = 24;
|
|
var ivSize = 8;
|
|
|
|
var derivedBytes = forge.pbe.opensslDeriveBytes(
|
|
password, salt, keySize + ivSize);
|
|
var buffer = forge.util.createBuffer(derivedBytes);
|
|
var key = buffer.getBytes(keySize);
|
|
var iv = buffer.getBytes(ivSize);
|
|
|
|
var decipher = forge.cipher.createDecipher('3DES-CBC', key);
|
|
decipher.start({iv: iv});
|
|
decipher.update(input);
|
|
var result = decipher.finish(); // check 'result' for true/false
|
|
|
|
fs.writeFileSync(
|
|
'input.dec.txt', decipher.output.getBytes(), {encoding: 'binary'});
|
|
}
|
|
```
|
|
|
|
<a name="aes" />
|
|
|
|
### AES
|
|
|
|
Provides [AES][] encryption and decryption in [CBC][], [CFB][], [OFB][],
|
|
[CTR][], and [GCM][] modes. See [CIPHER](#cipher) for examples.
|
|
|
|
<a name="des" />
|
|
|
|
### DES
|
|
|
|
Provides [3DES][] and [DES][] encryption and decryption in [ECB][] and
|
|
[CBC][] modes. See [CIPHER](#cipher) for examples.
|
|
|
|
<a name="rc2" />
|
|
|
|
### RC2
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
// 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());
|
|
```
|
|
|
|
PKI
|
|
---
|
|
|
|
Provides [X.509][] certificate support, ED25519 key generation and
|
|
signing/verifying, and RSA public and private key encoding, decoding,
|
|
encryption/decryption, and signing/verifying.
|
|
|
|
<a name="ed25519" />
|
|
|
|
### ED25519
|
|
|
|
Special thanks to [TweetNaCl.js][] for providing the bulk of the implementation.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
var ed25519 = forge.pki.ed25519;
|
|
|
|
// generate a random ED25519 keypair
|
|
var keypair = ed25519.generateKeyPair();
|
|
// `keypair.publicKey` is a node.js Buffer or Uint8Array
|
|
// `keypair.privateKey` is a node.js Buffer or Uint8Array
|
|
|
|
// generate a random ED25519 keypair based on a random 32-byte seed
|
|
var seed = forge.random.getBytesSync(32);
|
|
var keypair = ed25519.generateKeyPair({seed: seed});
|
|
|
|
// generate a random ED25519 keypair based on a "password" 32-byte seed
|
|
var password = 'Mai9ohgh6ahxee0jutheew0pungoozil';
|
|
var seed = new forge.util.ByteBuffer(password, 'utf8');
|
|
var keypair = ed25519.generateKeyPair({seed: seed});
|
|
|
|
// sign a UTF-8 message
|
|
var signature = ED25519.sign({
|
|
message: 'test',
|
|
// also accepts `binary` if you want to pass a binary string
|
|
encoding: 'utf8',
|
|
// node.js Buffer, Uint8Array, forge ByteBuffer, binary string
|
|
privateKey: privateKey
|
|
});
|
|
// `signature` is a node.js Buffer or Uint8Array
|
|
|
|
// sign a message passed as a buffer
|
|
var signature = ED25519.sign({
|
|
// also accepts a forge ByteBuffer or Uint8Array
|
|
message: Buffer.from('test', 'utf8'),
|
|
privateKey: privateKey
|
|
});
|
|
|
|
// sign a message digest (shorter "message" == better performance)
|
|
var md = forge.md.sha256.create();
|
|
md.update('test', 'utf8');
|
|
var signature = ED25519.sign({
|
|
md: md,
|
|
privateKey: privateKey
|
|
});
|
|
|
|
// verify a signature on a UTF-8 message
|
|
var verified = ED25519.verify({
|
|
message: 'test',
|
|
encoding: 'utf8',
|
|
// node.js Buffer, Uint8Array, forge ByteBuffer, or binary string
|
|
signature: signature,
|
|
// node.js Buffer, Uint8Array, forge ByteBuffer, or binary string
|
|
publicKey: publicKey
|
|
});
|
|
// `verified` is true/false
|
|
|
|
// sign a message passed as a buffer
|
|
var verified = ED25519.verify({
|
|
// also accepts a forge ByteBuffer or Uint8Array
|
|
message: Buffer.from('test', 'utf8'),
|
|
// node.js Buffer, Uint8Array, forge ByteBuffer, or binary string
|
|
signature: signature,
|
|
// node.js Buffer, Uint8Array, forge ByteBuffer, or binary string
|
|
publicKey: publicKey
|
|
});
|
|
|
|
// verify a signature on a message digest
|
|
var md = forge.md.sha256.create();
|
|
md.update('test', 'utf8');
|
|
var verified = ED25519.verify({
|
|
md: md,
|
|
// node.js Buffer, Uint8Array, forge ByteBuffer, or binary string
|
|
signature: signature,
|
|
// node.js Buffer, Uint8Array, forge ByteBuffer, or binary string
|
|
publicKey: publicKey
|
|
});
|
|
```
|
|
|
|
<a name="rsa" />
|
|
|
|
### RSA
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
var rsa = forge.pki.rsa;
|
|
|
|
// generate an RSA key pair synchronously
|
|
// *NOT RECOMMENDED*: Can be significantly slower than async and may block
|
|
// JavaScript execution. Will use native Node.js 10.12.0+ API if possible.
|
|
var keypair = rsa.generateKeyPair({bits: 2048, e: 0x10001});
|
|
|
|
// generate an RSA key pair asynchronously (uses web workers if available)
|
|
// use workers: -1 to run a fast core estimator to optimize # of workers
|
|
// *RECOMMENDED*: Can be significantly faster than sync. Will use native
|
|
// Node.js 10.12.0+ or WebCrypto API if possible.
|
|
rsa.generateKeyPair({bits: 2048, workers: 2}, function(err, keypair) {
|
|
// keypair.privateKey, keypair.publicKey
|
|
});
|
|
|
|
// generate an RSA key pair in steps that attempt to run for a specified period
|
|
// of time on the main JS thread
|
|
var state = rsa.createKeyPairGenerationState(2048, 0x10001);
|
|
var step = function() {
|
|
// run for 100 ms
|
|
if(!rsa.stepKeyPairGenerationState(state, 100)) {
|
|
setTimeout(step, 1);
|
|
}
|
|
else {
|
|
// done, turn off progress indicator, use state.keys
|
|
}
|
|
};
|
|
// turn on progress indicator, schedule generation to run
|
|
setTimeout(step);
|
|
|
|
// sign data with a private key and output DigestInfo DER-encoded bytes
|
|
// (defaults to RSASSA PKCS#1 v1.5)
|
|
var md = forge.md.sha1.create();
|
|
md.update('sign this', 'utf8');
|
|
var signature = privateKey.sign(md);
|
|
|
|
// verify data with a public key
|
|
// (defaults to RSASSA PKCS#1 v1.5)
|
|
var verified = publicKey.verify(md.digest().bytes(), signature);
|
|
|
|
// sign data using RSASSA-PSS where PSS uses a SHA-1 hash, a SHA-1 based
|
|
// masking function MGF1, and a 20 byte salt
|
|
var md = forge.md.sha1.create();
|
|
md.update('sign this', 'utf8');
|
|
var pss = forge.pss.create({
|
|
md: forge.md.sha1.create(),
|
|
mgf: forge.mgf.mgf1.create(forge.md.sha1.create()),
|
|
saltLength: 20
|
|
// optionally pass 'prng' with a custom PRNG implementation
|
|
// optionalls pass 'salt' with a forge.util.ByteBuffer w/custom salt
|
|
});
|
|
var signature = privateKey.sign(md, pss);
|
|
|
|
// verify RSASSA-PSS signature
|
|
var pss = forge.pss.create({
|
|
md: forge.md.sha1.create(),
|
|
mgf: forge.mgf.mgf1.create(forge.md.sha1.create()),
|
|
saltLength: 20
|
|
// optionally pass 'prng' with a custom PRNG implementation
|
|
});
|
|
var md = forge.md.sha1.create();
|
|
md.update('sign this', 'utf8');
|
|
publicKey.verify(md.digest().getBytes(), signature, pss);
|
|
|
|
// encrypt data with a public key (defaults to RSAES PKCS#1 v1.5)
|
|
var encrypted = publicKey.encrypt(bytes);
|
|
|
|
// decrypt data with a private key (defaults to RSAES PKCS#1 v1.5)
|
|
var decrypted = privateKey.decrypt(encrypted);
|
|
|
|
// encrypt data with a public key using RSAES PKCS#1 v1.5
|
|
var encrypted = publicKey.encrypt(bytes, 'RSAES-PKCS1-V1_5');
|
|
|
|
// decrypt data with a private key using RSAES PKCS#1 v1.5
|
|
var decrypted = privateKey.decrypt(encrypted, 'RSAES-PKCS1-V1_5');
|
|
|
|
// encrypt data with a public key using RSAES-OAEP
|
|
var encrypted = publicKey.encrypt(bytes, 'RSA-OAEP');
|
|
|
|
// decrypt data with a private key using RSAES-OAEP
|
|
var decrypted = privateKey.decrypt(encrypted, 'RSA-OAEP');
|
|
|
|
// encrypt data with a public key using RSAES-OAEP/SHA-256
|
|
var encrypted = publicKey.encrypt(bytes, 'RSA-OAEP', {
|
|
md: forge.md.sha256.create()
|
|
});
|
|
|
|
// decrypt data with a private key using RSAES-OAEP/SHA-256
|
|
var decrypted = privateKey.decrypt(encrypted, 'RSA-OAEP', {
|
|
md: forge.md.sha256.create()
|
|
});
|
|
|
|
// encrypt data with a public key using RSAES-OAEP/SHA-256/MGF1-SHA-1
|
|
// compatible with Java's RSA/ECB/OAEPWithSHA-256AndMGF1Padding
|
|
var encrypted = publicKey.encrypt(bytes, 'RSA-OAEP', {
|
|
md: forge.md.sha256.create(),
|
|
mgf1: {
|
|
md: forge.md.sha1.create()
|
|
}
|
|
});
|
|
|
|
// decrypt data with a private key using RSAES-OAEP/SHA-256/MGF1-SHA-1
|
|
// compatible with Java's RSA/ECB/OAEPWithSHA-256AndMGF1Padding
|
|
var decrypted = privateKey.decrypt(encrypted, 'RSA-OAEP', {
|
|
md: forge.md.sha256.create(),
|
|
mgf1: {
|
|
md: forge.md.sha1.create()
|
|
}
|
|
});
|
|
|
|
```
|
|
|
|
<a name="rsakem" />
|
|
|
|
### RSA-KEM
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
// generate an RSA key pair asynchronously (uses web workers if available)
|
|
// use workers: -1 to run a fast core estimator to optimize # of workers
|
|
forge.rsa.generateKeyPair({bits: 2048, workers: -1}, function(err, keypair) {
|
|
// keypair.privateKey, keypair.publicKey
|
|
});
|
|
|
|
// generate and encapsulate a 16-byte secret key
|
|
var kdf1 = new forge.kem.kdf1(forge.md.sha1.create());
|
|
var kem = forge.kem.rsa.create(kdf1);
|
|
var result = kem.encrypt(keypair.publicKey, 16);
|
|
// result has 'encapsulation' and 'key'
|
|
|
|
// encrypt some bytes
|
|
var iv = forge.random.getBytesSync(12);
|
|
var someBytes = 'hello world!';
|
|
var cipher = forge.cipher.createCipher('AES-GCM', result.key);
|
|
cipher.start({iv: iv});
|
|
cipher.update(forge.util.createBuffer(someBytes));
|
|
cipher.finish();
|
|
var encrypted = cipher.output.getBytes();
|
|
var tag = cipher.mode.tag.getBytes();
|
|
|
|
// send 'encrypted', 'iv', 'tag', and result.encapsulation to recipient
|
|
|
|
// decrypt encapsulated 16-byte secret key
|
|
var kdf1 = new forge.kem.kdf1(forge.md.sha1.create());
|
|
var kem = forge.kem.rsa.create(kdf1);
|
|
var key = kem.decrypt(keypair.privateKey, result.encapsulation, 16);
|
|
|
|
// decrypt some bytes
|
|
var decipher = forge.cipher.createDecipher('AES-GCM', key);
|
|
decipher.start({iv: iv, tag: tag});
|
|
decipher.update(forge.util.createBuffer(encrypted));
|
|
var pass = decipher.finish();
|
|
// pass is false if there was a failure (eg: authentication tag didn't match)
|
|
if(pass) {
|
|
// outputs 'hello world!'
|
|
console.log(decipher.output.getBytes());
|
|
}
|
|
|
|
```
|
|
|
|
<a name="x509" />
|
|
|
|
### X.509
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
var pki = forge.pki;
|
|
|
|
// convert a PEM-formatted public key to a Forge public key
|
|
var publicKey = pki.publicKeyFromPem(pem);
|
|
|
|
// convert a Forge public key to PEM-format
|
|
var pem = pki.publicKeyToPem(publicKey);
|
|
|
|
// convert an ASN.1 SubjectPublicKeyInfo to a Forge public key
|
|
var publicKey = pki.publicKeyFromAsn1(subjectPublicKeyInfo);
|
|
|
|
// convert a Forge public key to an ASN.1 SubjectPublicKeyInfo
|
|
var subjectPublicKeyInfo = pki.publicKeyToAsn1(publicKey);
|
|
|
|
// gets a SHA-1 RSAPublicKey fingerprint a byte buffer
|
|
pki.getPublicKeyFingerprint(key);
|
|
|
|
// gets a SHA-1 SubjectPublicKeyInfo fingerprint a byte buffer
|
|
pki.getPublicKeyFingerprint(key, {type: 'SubjectPublicKeyInfo'});
|
|
|
|
// gets a hex-encoded, colon-delimited SHA-1 RSAPublicKey public key fingerprint
|
|
pki.getPublicKeyFingerprint(key, {encoding: 'hex', delimiter: ':'});
|
|
|
|
// gets a hex-encoded, colon-delimited SHA-1 SubjectPublicKeyInfo public key fingerprint
|
|
pki.getPublicKeyFingerprint(key, {
|
|
type: 'SubjectPublicKeyInfo',
|
|
encoding: 'hex',
|
|
delimiter: ':'
|
|
});
|
|
|
|
// gets a hex-encoded, colon-delimited MD5 RSAPublicKey public key fingerprint
|
|
pki.getPublicKeyFingerprint(key, {
|
|
md: forge.md.md5.create(),
|
|
encoding: 'hex',
|
|
delimiter: ':'
|
|
});
|
|
|
|
// creates a CA store
|
|
var caStore = pki.createCaStore([/* PEM-encoded cert */, ...]);
|
|
|
|
// add a certificate to the CA store
|
|
caStore.addCertificate(certObjectOrPemString);
|
|
|
|
// gets the issuer (its certificate) for the given certificate
|
|
var issuerCert = caStore.getIssuer(subjectCert);
|
|
|
|
// verifies a certificate chain against a CA store
|
|
pki.verifyCertificateChain(caStore, chain, customVerifyCallback);
|
|
|
|
// signs a certificate using the given private key
|
|
cert.sign(privateKey);
|
|
|
|
// signs a certificate using SHA-256 instead of SHA-1
|
|
cert.sign(privateKey, forge.md.sha256.create());
|
|
|
|
// verifies an issued certificate using the certificates public key
|
|
var verified = issuer.verify(issued);
|
|
|
|
// generate a keypair and create an X.509v3 certificate
|
|
var keys = pki.rsa.generateKeyPair(2048);
|
|
var cert = pki.createCertificate();
|
|
cert.publicKey = keys.publicKey;
|
|
// alternatively set public key from a csr
|
|
//cert.publicKey = csr.publicKey;
|
|
// NOTE: serialNumber is the hex encoded value of an ASN.1 INTEGER.
|
|
// Conforming CAs should ensure serialNumber is:
|
|
// - no more than 20 octets
|
|
// - non-negative (prefix a '00' if your value starts with a '1' bit)
|
|
cert.serialNumber = '01';
|
|
cert.validity.notBefore = new Date();
|
|
cert.validity.notAfter = new Date();
|
|
cert.validity.notAfter.setFullYear(cert.validity.notBefore.getFullYear() + 1);
|
|
var attrs = [{
|
|
name: 'commonName',
|
|
value: 'example.org'
|
|
}, {
|
|
name: 'countryName',
|
|
value: 'US'
|
|
}, {
|
|
shortName: 'ST',
|
|
value: 'Virginia'
|
|
}, {
|
|
name: 'localityName',
|
|
value: 'Blacksburg'
|
|
}, {
|
|
name: 'organizationName',
|
|
value: 'Test'
|
|
}, {
|
|
shortName: 'OU',
|
|
value: 'Test'
|
|
}];
|
|
cert.setSubject(attrs);
|
|
// alternatively set subject from a csr
|
|
//cert.setSubject(csr.subject.attributes);
|
|
cert.setIssuer(attrs);
|
|
cert.setExtensions([{
|
|
name: 'basicConstraints',
|
|
cA: true
|
|
}, {
|
|
name: 'keyUsage',
|
|
keyCertSign: true,
|
|
digitalSignature: true,
|
|
nonRepudiation: true,
|
|
keyEncipherment: true,
|
|
dataEncipherment: true
|
|
}, {
|
|
name: 'extKeyUsage',
|
|
serverAuth: true,
|
|
clientAuth: true,
|
|
codeSigning: true,
|
|
emailProtection: true,
|
|
timeStamping: true
|
|
}, {
|
|
name: 'nsCertType',
|
|
client: true,
|
|
server: true,
|
|
email: true,
|
|
objsign: true,
|
|
sslCA: true,
|
|
emailCA: true,
|
|
objCA: true
|
|
}, {
|
|
name: 'subjectAltName',
|
|
altNames: [{
|
|
type: 6, // URI
|
|
value: 'http://example.org/webid#me'
|
|
}, {
|
|
type: 7, // IP
|
|
ip: '127.0.0.1'
|
|
}]
|
|
}, {
|
|
name: 'subjectKeyIdentifier'
|
|
}]);
|
|
/* alternatively set extensions from a csr
|
|
var extensions = csr.getAttribute({name: 'extensionRequest'}).extensions;
|
|
// optionally add more extensions
|
|
extensions.push.apply(extensions, [{
|
|
name: 'basicConstraints',
|
|
cA: true
|
|
}, {
|
|
name: 'keyUsage',
|
|
keyCertSign: true,
|
|
digitalSignature: true,
|
|
nonRepudiation: true,
|
|
keyEncipherment: true,
|
|
dataEncipherment: true
|
|
}]);
|
|
cert.setExtensions(extensions);
|
|
*/
|
|
// self-sign certificate
|
|
cert.sign(keys.privateKey);
|
|
|
|
// convert a Forge certificate to PEM
|
|
var pem = pki.certificateToPem(cert);
|
|
|
|
// convert a Forge certificate from PEM
|
|
var cert = pki.certificateFromPem(pem);
|
|
|
|
// convert an ASN.1 X.509x3 object to a Forge certificate
|
|
var cert = pki.certificateFromAsn1(obj);
|
|
|
|
// convert a Forge certificate to an ASN.1 X.509v3 object
|
|
var asn1Cert = pki.certificateToAsn1(cert);
|
|
```
|
|
|
|
<a name="pkcs5" />
|
|
|
|
### PKCS#5
|
|
|
|
Provides the password-based key-derivation function from [PKCS#5][].
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
// 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
|
|
});
|
|
```
|
|
|
|
<a name="pkcs7" />
|
|
|
|
### PKCS#7
|
|
|
|
Provides cryptographically protected messages from [PKCS#7][].
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
// convert a message from PEM
|
|
var p7 = forge.pkcs7.messageFromPem(pem);
|
|
// look at p7.recipients
|
|
|
|
// find a recipient by the issuer of a certificate
|
|
var recipient = p7.findRecipient(cert);
|
|
|
|
// decrypt
|
|
p7.decrypt(p7.recipients[0], privateKey);
|
|
|
|
// create a p7 enveloped message
|
|
var p7 = forge.pkcs7.createEnvelopedData();
|
|
|
|
// add a recipient
|
|
var cert = forge.pki.certificateFromPem(certPem);
|
|
p7.addRecipient(cert);
|
|
|
|
// set content
|
|
p7.content = forge.util.createBuffer('Hello');
|
|
|
|
// encrypt
|
|
p7.encrypt();
|
|
|
|
// convert message to PEM
|
|
var pem = forge.pkcs7.messageToPem(p7);
|
|
|
|
// create a degenerate PKCS#7 certificate container
|
|
// (CRLs not currently supported, only certificates)
|
|
var p7 = forge.pkcs7.createSignedData();
|
|
p7.addCertificate(certOrCertPem1);
|
|
p7.addCertificate(certOrCertPem2);
|
|
var pem = forge.pkcs7.messageToPem(p7);
|
|
|
|
// create PKCS#7 signed data with authenticatedAttributes
|
|
// attributes include: PKCS#9 content-type, message-digest, and signing-time
|
|
var p7 = forge.pkcs7.createSignedData();
|
|
p7.content = forge.util.createBuffer('Some content to be signed.', 'utf8');
|
|
p7.addCertificate(certOrCertPem);
|
|
p7.addSigner({
|
|
key: privateKeyAssociatedWithCert,
|
|
certificate: certOrCertPem,
|
|
digestAlgorithm: forge.pki.oids.sha256,
|
|
authenticatedAttributes: [{
|
|
type: forge.pki.oids.contentType,
|
|
value: forge.pki.oids.data
|
|
}, {
|
|
type: forge.pki.oids.messageDigest
|
|
// value will be auto-populated at signing time
|
|
}, {
|
|
type: forge.pki.oids.signingTime,
|
|
// value can also be auto-populated at signing time
|
|
value: new Date()
|
|
}]
|
|
});
|
|
p7.sign();
|
|
var pem = forge.pkcs7.messageToPem(p7);
|
|
|
|
// PKCS#7 Sign in detached mode.
|
|
// Includes the signature and certificate without the signed data.
|
|
p7.sign({detached: true});
|
|
|
|
```
|
|
|
|
<a name="pkcs8" />
|
|
|
|
### PKCS#8
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
var pki = forge.pki;
|
|
|
|
// convert a PEM-formatted private key to a Forge private key
|
|
var privateKey = pki.privateKeyFromPem(pem);
|
|
|
|
// convert a Forge private key to PEM-format
|
|
var pem = pki.privateKeyToPem(privateKey);
|
|
|
|
// convert an ASN.1 PrivateKeyInfo or RSAPrivateKey to a Forge private key
|
|
var privateKey = pki.privateKeyFromAsn1(rsaPrivateKey);
|
|
|
|
// convert a Forge private key to an ASN.1 RSAPrivateKey
|
|
var rsaPrivateKey = pki.privateKeyToAsn1(privateKey);
|
|
|
|
// wrap an RSAPrivateKey ASN.1 object in a PKCS#8 ASN.1 PrivateKeyInfo
|
|
var privateKeyInfo = pki.wrapRsaPrivateKey(rsaPrivateKey);
|
|
|
|
// convert a PKCS#8 ASN.1 PrivateKeyInfo to PEM
|
|
var pem = pki.privateKeyInfoToPem(privateKeyInfo);
|
|
|
|
// encrypts a PrivateKeyInfo using a custom password and
|
|
// outputs an EncryptedPrivateKeyInfo
|
|
var encryptedPrivateKeyInfo = pki.encryptPrivateKeyInfo(
|
|
privateKeyInfo, 'myCustomPasswordHere', {
|
|
algorithm: 'aes256', // 'aes128', 'aes192', 'aes256', '3des'
|
|
});
|
|
|
|
// decrypts an ASN.1 EncryptedPrivateKeyInfo that was encrypted
|
|
// with a custom password
|
|
var privateKeyInfo = pki.decryptPrivateKeyInfo(
|
|
encryptedPrivateKeyInfo, 'myCustomPasswordHere');
|
|
|
|
// converts an EncryptedPrivateKeyInfo to PEM
|
|
var pem = pki.encryptedPrivateKeyToPem(encryptedPrivateKeyInfo);
|
|
|
|
// converts a PEM-encoded EncryptedPrivateKeyInfo to ASN.1 format
|
|
var encryptedPrivateKeyInfo = pki.encryptedPrivateKeyFromPem(pem);
|
|
|
|
// wraps and encrypts a Forge private key and outputs it in PEM format
|
|
var pem = pki.encryptRsaPrivateKey(privateKey, 'password');
|
|
|
|
// encrypts a Forge private key and outputs it in PEM format using OpenSSL's
|
|
// proprietary legacy format + encapsulated PEM headers (DEK-Info)
|
|
var pem = pki.encryptRsaPrivateKey(privateKey, 'password', {legacy: true});
|
|
|
|
// decrypts a PEM-formatted, encrypted private key
|
|
var privateKey = pki.decryptRsaPrivateKey(pem, 'password');
|
|
|
|
// sets an RSA public key from a private key
|
|
var publicKey = pki.setRsaPublicKey(privateKey.n, privateKey.e);
|
|
```
|
|
|
|
<a name="pkcs10" />
|
|
|
|
### PKCS#10
|
|
|
|
Provides certification requests or certificate signing requests (CSR) from
|
|
[PKCS#10][].
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
// generate a key pair
|
|
var keys = forge.pki.rsa.generateKeyPair(1024);
|
|
|
|
// create a certification request (CSR)
|
|
var csr = forge.pki.createCertificationRequest();
|
|
csr.publicKey = keys.publicKey;
|
|
csr.setSubject([{
|
|
name: 'commonName',
|
|
value: 'example.org'
|
|
}, {
|
|
name: 'countryName',
|
|
value: 'US'
|
|
}, {
|
|
shortName: 'ST',
|
|
value: 'Virginia'
|
|
}, {
|
|
name: 'localityName',
|
|
value: 'Blacksburg'
|
|
}, {
|
|
name: 'organizationName',
|
|
value: 'Test'
|
|
}, {
|
|
shortName: 'OU',
|
|
value: 'Test'
|
|
}]);
|
|
// set (optional) attributes
|
|
csr.setAttributes([{
|
|
name: 'challengePassword',
|
|
value: 'password'
|
|
}, {
|
|
name: 'unstructuredName',
|
|
value: 'My Company, Inc.'
|
|
}, {
|
|
name: 'extensionRequest',
|
|
extensions: [{
|
|
name: 'subjectAltName',
|
|
altNames: [{
|
|
// 2 is DNS type
|
|
type: 2,
|
|
value: 'test.domain.com'
|
|
}, {
|
|
type: 2,
|
|
value: 'other.domain.com',
|
|
}, {
|
|
type: 2,
|
|
value: 'www.domain.net'
|
|
}]
|
|
}]
|
|
}]);
|
|
|
|
// sign certification request
|
|
csr.sign(keys.privateKey);
|
|
|
|
// verify certification request
|
|
var verified = csr.verify();
|
|
|
|
// convert certification request to PEM-format
|
|
var pem = forge.pki.certificationRequestToPem(csr);
|
|
|
|
// convert a Forge certification request from PEM-format
|
|
var csr = forge.pki.certificationRequestFromPem(pem);
|
|
|
|
// get an attribute
|
|
csr.getAttribute({name: 'challengePassword'});
|
|
|
|
// get extensions array
|
|
csr.getAttribute({name: 'extensionRequest'}).extensions;
|
|
|
|
```
|
|
|
|
<a name="pkcs12" />
|
|
|
|
### PKCS#12
|
|
|
|
Provides the cryptographic archive file format from [PKCS#12][].
|
|
|
|
**Note for Chrome/Firefox/iOS/similar users**: If you have trouble importing
|
|
a PKCS#12 container, try using the TripleDES algorithm. It can be passed
|
|
to `forge.pkcs12.toPkcs12Asn1` using the `{algorithm: '3des'}` option.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
// decode p12 from base64
|
|
var p12Der = forge.util.decode64(p12b64);
|
|
// get p12 as ASN.1 object
|
|
var p12Asn1 = forge.asn1.fromDer(p12Der);
|
|
// decrypt p12 using the password 'password'
|
|
var p12 = forge.pkcs12.pkcs12FromAsn1(p12Asn1, 'password');
|
|
// decrypt p12 using non-strict parsing mode (resolves some ASN.1 parse errors)
|
|
var p12 = forge.pkcs12.pkcs12FromAsn1(p12Asn1, false, 'password');
|
|
// decrypt p12 using literally no password (eg: Mac OS X/apple push)
|
|
var p12 = forge.pkcs12.pkcs12FromAsn1(p12Asn1);
|
|
// decrypt p12 using an "empty" password (eg: OpenSSL with no password input)
|
|
var p12 = forge.pkcs12.pkcs12FromAsn1(p12Asn1, '');
|
|
// p12.safeContents is an array of safe contents, each of
|
|
// which contains an array of safeBags
|
|
|
|
// get bags by friendlyName
|
|
var bags = p12.getBags({friendlyName: 'test'});
|
|
// bags are key'd by attribute type (here "friendlyName")
|
|
// and the key values are an array of matching objects
|
|
var cert = bags.friendlyName[0];
|
|
|
|
// get bags by localKeyId
|
|
var bags = p12.getBags({localKeyId: buffer});
|
|
// bags are key'd by attribute type (here "localKeyId")
|
|
// and the key values are an array of matching objects
|
|
var cert = bags.localKeyId[0];
|
|
|
|
// get bags by localKeyId (input in hex)
|
|
var bags = p12.getBags({localKeyIdHex: '7b59377ff142d0be4565e9ac3d396c01401cd879'});
|
|
// bags are key'd by attribute type (here "localKeyId", *not* "localKeyIdHex")
|
|
// and the key values are an array of matching objects
|
|
var cert = bags.localKeyId[0];
|
|
|
|
// get bags by type
|
|
var bags = p12.getBags({bagType: forge.pki.oids.certBag});
|
|
// bags are key'd by bagType and each bagType key's value
|
|
// is an array of matches (in this case, certificate objects)
|
|
var cert = bags[forge.pki.oids.certBag][0];
|
|
|
|
// get bags by friendlyName and filter on bag type
|
|
var bags = p12.getBags({
|
|
friendlyName: 'test',
|
|
bagType: forge.pki.oids.certBag
|
|
});
|
|
|
|
// get key bags
|
|
var bags = p12.getBags({bagType: forge.pki.oids.keyBag});
|
|
// get key
|
|
var bag = bags[forge.pki.oids.keyBag][0];
|
|
var key = bag.key;
|
|
// if the key is in a format unrecognized by forge then
|
|
// bag.key will be `null`, use bag.asn1 to get the ASN.1
|
|
// representation of the key
|
|
if(bag.key === null) {
|
|
var keyAsn1 = bag.asn1;
|
|
// can now convert back to DER/PEM/etc for export
|
|
}
|
|
|
|
// generate a p12 using AES (default)
|
|
var p12Asn1 = forge.pkcs12.toPkcs12Asn1(
|
|
privateKey, certificateChain, 'password');
|
|
|
|
// generate a p12 that can be imported by Chrome/Firefox/iOS
|
|
// (requires the use of Triple DES instead of AES)
|
|
var p12Asn1 = forge.pkcs12.toPkcs12Asn1(
|
|
privateKey, certificateChain, 'password',
|
|
{algorithm: '3des'});
|
|
|
|
// base64-encode p12
|
|
var p12Der = forge.asn1.toDer(p12Asn1).getBytes();
|
|
var p12b64 = forge.util.encode64(p12Der);
|
|
|
|
// create download link for p12
|
|
var a = document.createElement('a');
|
|
a.download = 'example.p12';
|
|
a.setAttribute('href', 'data:application/x-pkcs12;base64,' + p12b64);
|
|
a.appendChild(document.createTextNode('Download'));
|
|
```
|
|
|
|
<a name="asn" />
|
|
|
|
### ASN.1
|
|
|
|
Provides [ASN.1][] DER encoding and decoding.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
var asn1 = forge.asn1;
|
|
|
|
// create a SubjectPublicKeyInfo
|
|
var subjectPublicKeyInfo =
|
|
asn1.create(asn1.Class.UNIVERSAL, asn1.Type.SEQUENCE, true, [
|
|
// AlgorithmIdentifier
|
|
asn1.create(asn1.Class.UNIVERSAL, asn1.Type.SEQUENCE, true, [
|
|
// algorithm
|
|
asn1.create(asn1.Class.UNIVERSAL, asn1.Type.OID, false,
|
|
asn1.oidToDer(pki.oids['rsaEncryption']).getBytes()),
|
|
// parameters (null)
|
|
asn1.create(asn1.Class.UNIVERSAL, asn1.Type.NULL, false, '')
|
|
]),
|
|
// subjectPublicKey
|
|
asn1.create(asn1.Class.UNIVERSAL, asn1.Type.BITSTRING, false, [
|
|
// RSAPublicKey
|
|
asn1.create(asn1.Class.UNIVERSAL, asn1.Type.SEQUENCE, true, [
|
|
// modulus (n)
|
|
asn1.create(asn1.Class.UNIVERSAL, asn1.Type.INTEGER, false,
|
|
_bnToBytes(key.n)),
|
|
// publicExponent (e)
|
|
asn1.create(asn1.Class.UNIVERSAL, asn1.Type.INTEGER, false,
|
|
_bnToBytes(key.e))
|
|
])
|
|
])
|
|
]);
|
|
|
|
// serialize an ASN.1 object to DER format
|
|
var derBuffer = asn1.toDer(subjectPublicKeyInfo);
|
|
|
|
// deserialize to an ASN.1 object from a byte buffer filled with DER data
|
|
var object = asn1.fromDer(derBuffer);
|
|
|
|
// convert an OID dot-separated string to a byte buffer
|
|
var derOidBuffer = asn1.oidToDer('1.2.840.113549.1.1.5');
|
|
|
|
// convert a byte buffer with a DER-encoded OID to a dot-separated string
|
|
console.log(asn1.derToOid(derOidBuffer));
|
|
// output: 1.2.840.113549.1.1.5
|
|
|
|
// validates that an ASN.1 object matches a particular ASN.1 structure and
|
|
// captures data of interest from that structure for easy access
|
|
var publicKeyValidator = {
|
|
name: 'SubjectPublicKeyInfo',
|
|
tagClass: asn1.Class.UNIVERSAL,
|
|
type: asn1.Type.SEQUENCE,
|
|
constructed: true,
|
|
captureAsn1: 'subjectPublicKeyInfo',
|
|
value: [{
|
|
name: 'SubjectPublicKeyInfo.AlgorithmIdentifier',
|
|
tagClass: asn1.Class.UNIVERSAL,
|
|
type: asn1.Type.SEQUENCE,
|
|
constructed: true,
|
|
value: [{
|
|
name: 'AlgorithmIdentifier.algorithm',
|
|
tagClass: asn1.Class.UNIVERSAL,
|
|
type: asn1.Type.OID,
|
|
constructed: false,
|
|
capture: 'publicKeyOid'
|
|
}]
|
|
}, {
|
|
// subjectPublicKey
|
|
name: 'SubjectPublicKeyInfo.subjectPublicKey',
|
|
tagClass: asn1.Class.UNIVERSAL,
|
|
type: asn1.Type.BITSTRING,
|
|
constructed: false,
|
|
value: [{
|
|
// RSAPublicKey
|
|
name: 'SubjectPublicKeyInfo.subjectPublicKey.RSAPublicKey',
|
|
tagClass: asn1.Class.UNIVERSAL,
|
|
type: asn1.Type.SEQUENCE,
|
|
constructed: true,
|
|
optional: true,
|
|
captureAsn1: 'rsaPublicKey'
|
|
}]
|
|
}]
|
|
};
|
|
|
|
var capture = {};
|
|
var errors = [];
|
|
if(!asn1.validate(
|
|
publicKeyValidator, subjectPublicKeyInfo, validator, capture, errors)) {
|
|
throw 'ASN.1 object is not a SubjectPublicKeyInfo.';
|
|
}
|
|
// capture.subjectPublicKeyInfo contains the full ASN.1 object
|
|
// capture.rsaPublicKey contains the full ASN.1 object for the RSA public key
|
|
// capture.publicKeyOid only contains the value for the OID
|
|
var oid = asn1.derToOid(capture.publicKeyOid);
|
|
if(oid !== pki.oids['rsaEncryption']) {
|
|
throw 'Unsupported OID.';
|
|
}
|
|
|
|
// pretty print an ASN.1 object to a string for debugging purposes
|
|
asn1.prettyPrint(object);
|
|
```
|
|
|
|
Message Digests
|
|
----------------
|
|
|
|
<a name="sha1" />
|
|
|
|
### SHA1
|
|
|
|
Provides [SHA-1][] message digests.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
var md = forge.md.sha1.create();
|
|
md.update('The quick brown fox jumps over the lazy dog');
|
|
console.log(md.digest().toHex());
|
|
// output: 2fd4e1c67a2d28fced849ee1bb76e7391b93eb12
|
|
```
|
|
|
|
<a name="sha256" />
|
|
|
|
### SHA256
|
|
|
|
Provides [SHA-256][] message digests.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
var md = forge.md.sha256.create();
|
|
md.update('The quick brown fox jumps over the lazy dog');
|
|
console.log(md.digest().toHex());
|
|
// output: d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592
|
|
```
|
|
|
|
<a name="sha384" />
|
|
|
|
### SHA384
|
|
|
|
Provides [SHA-384][] message digests.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
var md = forge.md.sha384.create();
|
|
md.update('The quick brown fox jumps over the lazy dog');
|
|
console.log(md.digest().toHex());
|
|
// output: ca737f1014a48f4c0b6dd43cb177b0afd9e5169367544c494011e3317dbf9a509cb1e5dc1e85a941bbee3d7f2afbc9b1
|
|
```
|
|
|
|
<a name="sha512" />
|
|
|
|
### SHA512
|
|
|
|
Provides [SHA-512][] message digests.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
// SHA-512
|
|
var md = forge.md.sha512.create();
|
|
md.update('The quick brown fox jumps over the lazy dog');
|
|
console.log(md.digest().toHex());
|
|
// output: 07e547d9586f6a73f73fbac0435ed76951218fb7d0c8d788a309d785436bbb642e93a252a954f23912547d1e8a3b5ed6e1bfd7097821233fa0538f3db854fee6
|
|
|
|
// SHA-512/224
|
|
var md = forge.md.sha512.sha224.create();
|
|
md.update('The quick brown fox jumps over the lazy dog');
|
|
console.log(md.digest().toHex());
|
|
// output: 944cd2847fb54558d4775db0485a50003111c8e5daa63fe722c6aa37
|
|
|
|
// SHA-512/256
|
|
var md = forge.md.sha512.sha256.create();
|
|
md.update('The quick brown fox jumps over the lazy dog');
|
|
console.log(md.digest().toHex());
|
|
// output: dd9d67b371519c339ed8dbd25af90e976a1eeefd4ad3d889005e532fc5bef04d
|
|
```
|
|
|
|
<a name="md5" />
|
|
|
|
### MD5
|
|
|
|
Provides [MD5][] message digests.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
var md = forge.md.md5.create();
|
|
md.update('The quick brown fox jumps over the lazy dog');
|
|
console.log(md.digest().toHex());
|
|
// output: 9e107d9d372bb6826bd81d3542a419d6
|
|
```
|
|
|
|
<a name="hmac" />
|
|
|
|
### HMAC
|
|
|
|
Provides [HMAC][] w/any supported message digest algorithm.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
var hmac = forge.hmac.create();
|
|
hmac.start('sha1', 'Jefe');
|
|
hmac.update('what do ya want for nothing?');
|
|
console.log(hmac.digest().toHex());
|
|
// output: effcdf6ae5eb2fa2d27416d5f184df9c259a7c79
|
|
```
|
|
|
|
Utilities
|
|
---------
|
|
|
|
<a name="prime" />
|
|
|
|
### Prime
|
|
|
|
Provides an API for generating large, random, probable primes.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
// generate a random prime on the main JS thread
|
|
var bits = 1024;
|
|
forge.prime.generateProbablePrime(bits, function(err, num) {
|
|
console.log('random prime', num.toString(16));
|
|
});
|
|
|
|
// generate a random prime using Web Workers (if available, otherwise
|
|
// falls back to the main thread)
|
|
var bits = 1024;
|
|
var options = {
|
|
algorithm: {
|
|
name: 'PRIMEINC',
|
|
workers: -1 // auto-optimize # of workers
|
|
}
|
|
};
|
|
forge.prime.generateProbablePrime(bits, options, function(err, num) {
|
|
console.log('random prime', num.toString(16));
|
|
});
|
|
```
|
|
|
|
<a name="prng" />
|
|
|
|
### PRNG
|
|
|
|
Provides a [Fortuna][]-based cryptographically-secure pseudo-random number
|
|
generator, to be used with a cryptographic function backend, e.g. [AES][]. An
|
|
implementation using [AES][] as a backend is provided. An API for collecting
|
|
entropy is given, though if window.crypto.getRandomValues is available, it will
|
|
be used automatically.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
// get some random bytes synchronously
|
|
var bytes = forge.random.getBytesSync(32);
|
|
console.log(forge.util.bytesToHex(bytes));
|
|
|
|
// get some random bytes asynchronously
|
|
forge.random.getBytes(32, function(err, bytes) {
|
|
console.log(forge.util.bytesToHex(bytes));
|
|
});
|
|
|
|
// collect some entropy if you'd like
|
|
forge.random.collect(someRandomBytes);
|
|
jQuery().mousemove(function(e) {
|
|
forge.random.collectInt(e.clientX, 16);
|
|
forge.random.collectInt(e.clientY, 16);
|
|
});
|
|
|
|
// specify a seed file for use with the synchronous API if you'd like
|
|
forge.random.seedFileSync = function(needed) {
|
|
// get 'needed' number of random bytes from somewhere
|
|
return fetchedRandomBytes;
|
|
};
|
|
|
|
// specify a seed file for use with the asynchronous API if you'd like
|
|
forge.random.seedFile = function(needed, callback) {
|
|
// get the 'needed' number of random bytes from somewhere
|
|
callback(null, fetchedRandomBytes);
|
|
});
|
|
|
|
// register the main thread to send entropy or a Web Worker to receive
|
|
// entropy on demand from the main thread
|
|
forge.random.registerWorker(self);
|
|
|
|
// generate a new instance of a PRNG with no collected entropy
|
|
var myPrng = forge.random.createInstance();
|
|
```
|
|
|
|
<a name="task" />
|
|
|
|
### Tasks
|
|
|
|
Provides queuing and synchronizing tasks in a web application.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
// TODO
|
|
```
|
|
|
|
<a name="util" />
|
|
|
|
### Utilities
|
|
|
|
Provides utility functions, including byte buffer support, base64,
|
|
bytes to/from hex, zlib inflate/deflate, etc.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
// encode/decode base64
|
|
var encoded = forge.util.encode64(str);
|
|
var str = forge.util.decode64(encoded);
|
|
|
|
// encode/decode UTF-8
|
|
var encoded = forge.util.encodeUtf8(str);
|
|
var str = forge.util.decodeUtf8(encoded);
|
|
|
|
// bytes to/from hex
|
|
var bytes = forge.util.hexToBytes(hex);
|
|
var hex = forge.util.bytesToHex(bytes);
|
|
|
|
// create an empty byte buffer
|
|
var buffer = forge.util.createBuffer();
|
|
// create a byte buffer from raw binary bytes
|
|
var buffer = forge.util.createBuffer(input, 'raw');
|
|
// create a byte buffer from utf8 bytes
|
|
var buffer = forge.util.createBuffer(input, 'utf8');
|
|
|
|
// get the length of the buffer in bytes
|
|
buffer.length();
|
|
// put bytes into the buffer
|
|
buffer.putBytes(bytes);
|
|
// put a 32-bit integer into the buffer
|
|
buffer.putInt32(10);
|
|
// buffer to hex
|
|
buffer.toHex();
|
|
// get a copy of the bytes in the buffer
|
|
bytes.bytes(/* count */);
|
|
// empty this buffer and get its contents
|
|
bytes.getBytes(/* count */);
|
|
|
|
// convert a forge buffer into a Node.js Buffer
|
|
// make sure you specify the encoding as 'binary'
|
|
var forgeBuffer = forge.util.createBuffer();
|
|
var nodeBuffer = Buffer.from(forgeBuffer.getBytes(), 'binary');
|
|
|
|
// convert a Node.js Buffer into a forge buffer
|
|
// make sure you specify the encoding as 'binary'
|
|
var nodeBuffer = Buffer.from('CAFE', 'hex');
|
|
var forgeBuffer = forge.util.createBuffer(nodeBuffer.toString('binary'));
|
|
|
|
// parse a URL
|
|
var parsed = forge.util.parseUrl('http://example.com/foo?bar=baz');
|
|
// parsed.scheme, parsed.host, parsed.port, parsed.path, parsed.fullHost
|
|
```
|
|
|
|
<a name="log" />
|
|
|
|
### Logging
|
|
|
|
Provides logging to a javascript console using various categories and
|
|
levels of verbosity.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
// TODO
|
|
```
|
|
|
|
<a name="debug" />
|
|
|
|
### Debugging
|
|
|
|
Provides storage of debugging information normally inaccessible in
|
|
closures for viewing/investigation.
|
|
|
|
__Examples__
|
|
|
|
```js
|
|
// TODO
|
|
```
|
|
|
|
<a name="flash" />
|
|
|
|
### Flash Networking Support
|
|
|
|
The [flash README](./flash/README.md) provides details on rebuilding the
|
|
optional Flash component used for networking. It also provides details on
|
|
Policy Server support.
|
|
|
|
Security Considerations
|
|
-----------------------
|
|
|
|
When using this code please keep the following in mind:
|
|
|
|
- Cryptography is hard. Please review and test this code before depending on it
|
|
for critical functionality.
|
|
- The nature of JavaScript is that execution of this code depends on trusting a
|
|
very large set of JavaScript tools and systems. Consider runtime variations,
|
|
runtime characteristics, runtime optimization, code optimization, code
|
|
minimization, code obfuscation, bundling tools, possible bugs, the Forge code
|
|
itself, and so on.
|
|
- If using pre-built bundles from [Bower][] or similar be aware someone else
|
|
ran the tools to create those files.
|
|
- Use a secure transport channel such as [TLS][] to load scripts and consider
|
|
using additional security mechanisms such as [Subresource Integrity][] script
|
|
attributes.
|
|
- Use "native" functionality where possible. This can be critical when dealing
|
|
with performance and random number generation. Note that the JavaScript
|
|
random number algorithms should perform well if given suitable entropy.
|
|
- Understand possible attacks against cryptographic systems. For instance side
|
|
channel and timing attacks may be possible due to the difficulty in
|
|
implementing constant time algorithms in pure JavaScript.
|
|
- Certain features in this library are less susceptible to attacks depending on
|
|
usage. This primarily includes features that deal with data format
|
|
manipulation or those that are not involved in communication.
|
|
|
|
Library Background
|
|
------------------
|
|
|
|
* https://digitalbazaar.com/2010/07/20/javascript-tls-1/
|
|
* https://digitalbazaar.com/2010/07/20/javascript-tls-2/
|
|
|
|
Contact
|
|
-------
|
|
|
|
* Code: https://github.com/digitalbazaar/forge
|
|
* Bugs: https://github.com/digitalbazaar/forge/issues
|
|
* Email: support@digitalbazaar.com
|
|
* IRC: [#forgejs][] on [freenode][]
|
|
|
|
Donations
|
|
---------
|
|
|
|
Financial support is welcome and helps contribute to futher development:
|
|
|
|
* For [PayPal][] please send to paypal@digitalbazaar.com.
|
|
* Something else? Please contact support@digitalbazaar.com.
|
|
|
|
[#forgejs]: https://webchat.freenode.net/?channels=#forgejs
|
|
[0.6.x]: https://github.com/digitalbazaar/forge/tree/0.6.x
|
|
[3DES]: https://en.wikipedia.org/wiki/Triple_DES
|
|
[AES]: https://en.wikipedia.org/wiki/Advanced_Encryption_Standard
|
|
[ASN.1]: https://en.wikipedia.org/wiki/ASN.1
|
|
[Bower]: https://bower.io/
|
|
[Browserify]: http://browserify.org/
|
|
[CBC]: https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation
|
|
[CFB]: https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation
|
|
[CTR]: https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation
|
|
[CommonJS]: https://en.wikipedia.org/wiki/CommonJS
|
|
[DES]: https://en.wikipedia.org/wiki/Data_Encryption_Standard
|
|
[ECB]: https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation
|
|
[Fortuna]: https://en.wikipedia.org/wiki/Fortuna_(PRNG)
|
|
[GCM]: https://en.wikipedia.org/wiki/GCM_mode
|
|
[HMAC]: https://en.wikipedia.org/wiki/HMAC
|
|
[JavaScript]: https://en.wikipedia.org/wiki/JavaScript
|
|
[Karma]: https://karma-runner.github.io/
|
|
[MD5]: https://en.wikipedia.org/wiki/MD5
|
|
[Node.js]: https://nodejs.org/
|
|
[OFB]: https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation
|
|
[PKCS#10]: https://en.wikipedia.org/wiki/Certificate_signing_request
|
|
[PKCS#12]: https://en.wikipedia.org/wiki/PKCS_%E2%99%AF12
|
|
[PKCS#5]: https://en.wikipedia.org/wiki/PKCS
|
|
[PKCS#7]: https://en.wikipedia.org/wiki/Cryptographic_Message_Syntax
|
|
[PayPal]: https://www.paypal.com/
|
|
[RC2]: https://en.wikipedia.org/wiki/RC2
|
|
[SHA-1]: https://en.wikipedia.org/wiki/SHA-1
|
|
[SHA-256]: https://en.wikipedia.org/wiki/SHA-256
|
|
[SHA-384]: https://en.wikipedia.org/wiki/SHA-384
|
|
[SHA-512]: https://en.wikipedia.org/wiki/SHA-512
|
|
[Subresource Integrity]: https://www.w3.org/TR/SRI/
|
|
[TLS]: https://en.wikipedia.org/wiki/Transport_Layer_Security
|
|
[UMD]: https://github.com/umdjs/umd
|
|
[X.509]: https://en.wikipedia.org/wiki/X.509
|
|
[freenode]: https://freenode.net/
|
|
[unpkg]: https://unpkg.com/
|
|
[webpack]: https://webpack.github.io/
|
|
[TweetNaCl.js]: https://github.com/dchest/tweetnacl-js
|