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:
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:
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.
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 installnpm 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.
// create TLS clientvar 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 processclient.handshake();// when encrypted TLS data is received from the server, process itclient.process(encryptedBytesFromServer);// create TLS servervar 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 itserver.process(encryptedBytesFromClient);
Connect to a TLS server using node's net.Socket:
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.comsocket.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');
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
// generate a random key and IV// Note: a key size of 16 bytes will use AES-128, 24 => AES-192, 32 => AES-256var key = forge.random.getBytesSync(16);var iv = forge.random.getBytesSync(16);/* alternatively, generate a password-based 16-byte keyvar 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 defaultvar 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 hexconsole.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 hexconsole.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 modevar 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 hexconsole.log(encrypted.toHex());// outputs authentication tagconsole.log(tag.toHex());// decrypt some bytes using GCM modevar 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/GnuPG):
var forge = require('node-forge');var fs = require('fs');// openssl enc -des3 -in input.txt -out input.encfunction 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.txtfunction 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'});}
Provides X.509 certificate support, ED25519 key generation and
signing/verifying, and RSA public and private key encoding, decoding,
encryption/decryption, and signing/verifying.
var ed25519 = forge.pki.ed25519;// generate a random ED25519 keypairvar 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 seedvar seed = forge.random.getBytesSync(32);var keypair = ed25519.generateKeyPair({seed: seed});// generate a random ED25519 keypair based on a "password" 32-byte seedvar password = 'Mai9ohgh6ahxee0jutheew0pungoozil';var seed = new forge.util.ByteBuffer(password, 'utf8');var keypair = ed25519.generateKeyPair({seed: seed});// sign a UTF-8 messagevar 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 buffervar 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 messagevar 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 (always false for small-order public keys, such// as the identity point, which have no private key)// sign a message passed as a buffervar 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 digestvar 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});
// generate a password-based 16-byte key// note an optional message digest can be passed as the final parametervar 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 callbackforge.pkcs5.pbkdf2('password', salt, numIterations, 16, function(err, derivedKey) { // do something w/derivedKey});
// convert a message from PEMvar p7 = forge.pkcs7.messageFromPem(pem);// look at p7.recipients// find a recipient by the issuer of a certificatevar recipient = p7.findRecipient(cert);// decryptp7.decrypt(p7.recipients[0], privateKey);// create a p7 enveloped messagevar p7 = forge.pkcs7.createEnvelopedData();// add a recipientvar cert = forge.pki.certificateFromPem(certPem);p7.addRecipient(cert);// set contentp7.content = forge.util.createBuffer('Hello');// encryptp7.encrypt();// convert message to PEMvar 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-timevar 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});
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
// decode p12 from base64var p12Der = forge.util.decode64(p12b64);// get p12 as ASN.1 objectvar 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 friendlyNamevar bags = p12.getBags({friendlyName: 'test'});// bags are key'd by attribute type (here "friendlyName")// and the key values are an array of matching objectsvar cert = bags.friendlyName[0];// get bags by localKeyIdvar bags = p12.getBags({localKeyId: buffer});// bags are key'd by attribute type (here "localKeyId")// and the key values are an array of matching objectsvar 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 objectsvar cert = bags.localKeyId[0];// get bags by typevar 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 typevar bags = p12.getBags({ friendlyName: 'test', bagType: forge.pki.oids.certBag});// get key bagsvar bags = p12.getBags({bagType: forge.pki.oids.keyBag});// get keyvar 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 keyif(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 p12var p12Der = forge.asn1.toDer(p12Asn1).getBytes();var p12b64 = forge.util.encode64(p12Der);// create download link for p12var a = document.createElement('a');a.download = 'example.p12';a.setAttribute('href', 'data:application/x-pkcs12;base64,' + p12b64);a.appendChild(document.createTextNode('Download'));
var md = forge.md.sha1.create();md.update('The quick brown fox jumps over the lazy dog');console.log(md.digest().toHex());// output: 2fd4e1c67a2d28fced849ee1bb76e7391b93eb12
var md = forge.md.sha256.create();md.update('The quick brown fox jumps over the lazy dog');console.log(md.digest().toHex());// output: d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592
var md = forge.md.sha384.create();md.update('The quick brown fox jumps over the lazy dog');console.log(md.digest().toHex());// output: ca737f1014a48f4c0b6dd43cb177b0afd9e5169367544c494011e3317dbf9a509cb1e5dc1e85a941bbee3d7f2afbc9b1
// SHA-512var 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/224var 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/256var md = forge.md.sha512.sha256.create();md.update('The quick brown fox jumps over the lazy dog');console.log(md.digest().toHex());// output: dd9d67b371519c339ed8dbd25af90e976a1eeefd4ad3d889005e532fc5bef04d
var md = forge.md.md5.create();md.update('The quick brown fox jumps over the lazy dog');console.log(md.digest().toHex());// output: 9e107d9d372bb6826bd81d3542a419d6
var hmac = forge.hmac.create();hmac.start('sha1', 'Jefe');hmac.update('what do ya want for nothing?');console.log(hmac.digest().toHex());// output: effcdf6ae5eb2fa2d27416d5f184df9c259a7c79
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
// get some random bytes synchronouslyvar bytes = forge.random.getBytesSync(32);console.log(forge.util.bytesToHex(bytes));// get some random bytes asynchronouslyforge.random.getBytes(32, function(err, bytes) { console.log(forge.util.bytesToHex(bytes));});// collect some entropy if you'd likeforge.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 likeforge.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 likeforge.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 threadforge.random.registerWorker(self);// generate a new instance of a PRNG with no collected entropyvar myPrng = forge.random.createInstance();
The flash README 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 NPM, another CDN, 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.