node-forge 0.7.1 → 0.7.5

package/CHANGELOG.md

@@ -1,6 +1,38 @@
 Forge ChangeLog
 ===============
 
+## 0.7.5 - 2018-03-30
+
+### Fixed
+- Remove use of `const`.
+
+## 0.7.4 - 2018-03-07
+
+### Fixed
+- Potential regex denial of service in form.js.
+
+### Added
+- Support for ED25519.
+- Support for baseN/base58.
+
+## 0.7.3 - 2018-03-05
+
+- Re-publish with npm 5.6.0 due to file timestamp issues.
+
+## 0.7.2 - 2018-02-27
+
+### Added
+- Support verification of SHA-384 certificates.
+- `1.2.840.10040.4.3'`/`dsa-with-sha1` OID.
+
+### Fixed
+- Support importing PKCS#7 data with no certificates. RFC 2315 sec 9.1 states
+  certificates are optional.
+- `asn1.equals` loop bug.
+- Fortuna implementation bugs.
+
+## 0.7.1 - 2017-03-27
+
 ### Fixed
 
 - Fix digestLength for hashes based on SHA-512.

package/README.md

@@ -53,6 +53,7 @@ Documentation
 
 ### PKI
 
+* [ED25519](#ed25519)
 * [RSA](#rsa)
 * [RSA-KEM](#rsakem)
 * [X.509](#x509)
@@ -132,11 +133,21 @@ with [Bower][]:
 
     bower install forge
 
-### unpkg
+### jsDelivr CDN
 
-[unpkg][] provides a CDN that can serve files from npm packages directly.
+To use it via [jsDelivr](https://www.jsdelivr.com/package/npm/node-forge) include this in your html:
 
-https://unpkg.com/node-forge@0.7.0/dist/forge.min.js
+```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
 
@@ -285,6 +296,7 @@ API
 ---
 
 <a name="options" />
+
 ### Options
 
 If at any time you wish to disable the use of native code, where available,
@@ -313,6 +325,7 @@ Transports
 ----------
 
 <a name="tls" />
+
 ### TLS
 
 Provides a native javascript client and server-side [TLS][] implementation.
@@ -523,6 +536,7 @@ socket.connect(443, 'google.com');
 ```
 
 <a name="http" />
+
 ### HTTP
 
 Provides a native [JavaScript][] mini-implementation of an http client that
@@ -558,6 +572,7 @@ var someAsyncDataHandler = function(bytes) {
 ```
 
 <a name="ssh" />
+
 ### SSH
 
 Provides some SSH utility functions.
@@ -582,6 +597,7 @@ forge.ssh.getPublicKeyFingerprint(key, {encoding: 'hex', delimiter: ':'});
 ```
 
 <a name="xhr" />
+
 ### XHR
 
 Provides an XmlHttpRequest implementation using forge.http as a backend.
@@ -593,6 +609,7 @@ __Examples__
 ```
 
 <a name="socket" />
+
 ### Sockets
 
 Provides an interface to create and use raw sockets provided via Flash.
@@ -607,6 +624,7 @@ Ciphers
 -------
 
 <a name="cipher" />
+
 ### CIPHER
 
 Provides a basic API for block encryption and decryption. There is built-in
@@ -660,10 +678,35 @@ console.log(encrypted.toHex());
 var decipher = forge.cipher.createDecipher('AES-CBC', key);
 decipher.start({iv: iv});
 decipher.update(encrypted);
-decipher.finish();
+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({
@@ -776,18 +819,21 @@ function decrypt(password) {
 ```
 
 <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__
@@ -818,10 +864,95 @@ console.log(cipher.output.toHex());
 PKI
 ---
 
-Provides [X.509][] certificate and RSA public and private key encoding,
-decoding, encryption/decryption, and signing/verifying.
+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: new Buffer('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: new Buffer('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__
@@ -940,6 +1071,7 @@ var decrypted = privateKey.decrypt(encrypted, 'RSA-OAEP', {
 ```
 
 <a name="rsakem" />
+
 ### RSA-KEM
 
 __Examples__
@@ -988,6 +1120,7 @@ if(pass) {
 ```
 
 <a name="x509" />
+
 ### X.509
 
 __Examples__
@@ -1057,6 +1190,10 @@ 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();
@@ -1155,6 +1292,7 @@ var asn1Cert = pki.certificateToAsn1(cert);
 ```
 
 <a name="pkcs5" />
+
 ### PKCS#5
 
 Provides the password-based key-derivation function from [PKCS#5][].
@@ -1175,6 +1313,7 @@ forge.pkcs5.pbkdf2('password', salt, numIterations, 16, function(err, derivedKey
 ```
 
 <a name="pkcs7" />
+
 ### PKCS#7
 
 Provides cryptographically protected messages from [PKCS#7][].
@@ -1242,6 +1381,7 @@ var pem = forge.pkcs7.messageToPem(p7);
 ```
 
 <a name="pkcs8" />
+
 ### PKCS#8
 
 __Examples__
@@ -1298,6 +1438,7 @@ var publicKey = pki.setRsaPublicKey(privateKey.n, privateKey.e);
 ```
 
 <a name="pkcs10" />
+
 ### PKCS#10
 
 Provides certification requests or certificate signing requests (CSR) from
@@ -1377,6 +1518,7 @@ csr.getAttribute({name: 'extensionRequest'}).extensions;
 ```
 
 <a name="pkcs12" />
+
 ### PKCS#12
 
 Provides the cryptographic archive file format from [PKCS#12][].
@@ -1468,6 +1610,7 @@ a.appendChild(document.createTextNode('Download'));
 ```
 
 <a name="asn" />
+
 ### ASN.1
 
 Provides [ASN.1][] DER encoding and decoding.
@@ -1575,6 +1718,7 @@ Message Digests
 ----------------
 
 <a name="sha1" />
+
 ### SHA1
 
 Provides [SHA-1][] message digests.
@@ -1589,6 +1733,7 @@ console.log(md.digest().toHex());
 ```
 
 <a name="sha256" />
+
 ### SHA256
 
 Provides [SHA-256][] message digests.
@@ -1603,6 +1748,7 @@ console.log(md.digest().toHex());
 ```
 
 <a name="sha384" />
+
 ### SHA384
 
 Provides [SHA-384][] message digests.
@@ -1617,6 +1763,7 @@ console.log(md.digest().toHex());
 ```
 
 <a name="sha512" />
+
 ### SHA512
 
 Provides [SHA-512][] message digests.
@@ -1644,6 +1791,7 @@ console.log(md.digest().toHex());
 ```
 
 <a name="md5" />
+
 ### MD5
 
 Provides [MD5][] message digests.
@@ -1658,6 +1806,7 @@ console.log(md.digest().toHex());
 ```
 
 <a name="hmac" />
+
 ### HMAC
 
 Provides [HMAC][] w/any supported message digest algorithm.
@@ -1676,6 +1825,7 @@ Utilities
 ---------
 
 <a name="prime" />
+
 ### Prime
 
 Provides an API for generating large, random, probable primes.
@@ -1704,6 +1854,7 @@ forge.prime.generateProbablePrime(bits, options, function(err, num) {
 ```
 
 <a name="prng" />
+
 ### PRNG
 
 Provides a [Fortuna][]-based cryptographically-secure pseudo-random number
@@ -1752,6 +1903,7 @@ var myPrng = forge.random.createInstance();
 ```
 
 <a name="task" />
+
 ### Tasks
 
 Provides queuing and synchronizing tasks in a web application.
@@ -1763,6 +1915,7 @@ __Examples__
 ```
 
 <a name="util" />
+
 ### Utilities
 
 Provides utility functions, including byte buffer support, base64,
@@ -1819,6 +1972,7 @@ var parsed = forge.util.parseUrl('http://example.com/foo?bar=baz');
 ```
 
 <a name="log" />
+
 ### Logging
 
 Provides logging to a javascript console using various categories and
@@ -1831,6 +1985,7 @@ __Examples__
 ```
 
 <a name="debug" />
+
 ### Debugging
 
 Provides storage of debugging information normally inaccessible in
@@ -1843,6 +1998,7 @@ __Examples__
 ```
 
 <a name="flash" />
+
 ### Flash Networking Support
 
 The [flash README](./flash/README.md) provides details on rebuilding the
@@ -1936,3 +2092,4 @@ Financial support is welcome and helps contribute to futher development:
 [freenode]: https://freenode.net/
 [unpkg]: https://unpkg.com/
 [webpack]: https://webpack.github.io/
+[TweetNaCl]: https://github.com/dchest/tweetnacl-js