Readme for modifications to support RFC 6637 - Elliptic Curve Cryptography (ECC) in OpenPGP

README-ECC.md

@@ -0,0 +1,134 @@
+# Elliptic Curve Cryptography support for OpenPGPjs
+
+## Description
+
+This work is to provide an implementation of [RFC 6637](http://www.ietf.org/rfc/rfc6637.txt)
+for OpenPGP.js.
+
+## Compatibility with GnuPG
+
+In order to assure compatibility of the provided implementation with RFC 6637,
+the keys and messages were tested against GnuPG version v2.1.8, compiled
+with a beta version of libgcrypt v1.7.0-beta262.
+
+It was tested that keys, messages, and signatures generated by GnuPG
+were imported correctly. Also keys, messages and signatures generated by this
+implementation are correctly imported by GnuPG.
+
+```txt
+> gpg2 --homedir ../home --version
+gpg (GnuPG) 2.1.8
+libgcrypt 1.7.0-beta262
+Copyright (C) 2015 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+Home: ../home
+Supported algorithms:
+Pubkey: RSA, ELG, DSA, ECDH, ECDSA, EDDSA
+Cipher: IDEA, 3DES, CAST5, BLOWFISH, AES, AES192, AES256, TWOFISH,
+        CAMELLIA128, CAMELLIA192, CAMELLIA256
+Hash: SHA1, RIPEMD160, SHA256, SHA384, SHA512, SHA224
+Compression: Uncompressed, ZIP, ZLIB
+```
+
+## Extra dependencies
+
+There are two new dependencies:
+
+*   [Elliptic](https://github.com/indutny/elliptic/) for the elliptic curve
+    cryptography. MIT license.
+
+*   [Aes](https://github.com/cryptocoinjs/aes) required to implement RFC 3394
+    Key wrap and Key Unwrap functions. BSD License.
+
+## Examples
+
+### Generate new key
+
+```js
+var openpgp = require('openpgp');
+
+var options = {
+    curve: 'secp256k1',
+    userIds: {name: 'Hamlet', email: 'hamlet@example.net'},
+    passphrase: 'To be, or not to be: that is the question'
+};
+
+openpgp.generateKey(options).then(function(key) {
+    // success
+    var privkey = key.privateKeyArmored;
+    var pubkey = key.publicKeyArmored;
+}).catch(function(error) {
+    // failure
+});
+```
+
+### Generate keypair from bitcoin key
+
+```js
+var openpgp = require('openpgp');
+var bs58check = require('bs58check');
+
+var wif = 'KyiAchQgMKuXQu89j6k6UVZQj7brK6cM79JfmDvkNXPVW24L1thi';
+var buff = bs58check.decode(wif);
+var privateKey = buff.slice(1, -1);
+privateKey = openpgp.util.bin2str(privateKey);
+
+var options = {
+    curve: 'secp256k1',
+    userIds: {name: 'Hamlet', email: 'hamlet@example.net'},
+    passphrase: 'To be, or not to be: that is the question',
+    material: {
+      key: privateKey,
+      subkey: privateKey
+    }
+};
+
+openpgp.generateKey(options).then(function(key) {
+    // success
+    var privkey = key.privateKeyArmored;
+    var pubkey = key.publicKeyArmored;
+}).catch(function(error) {
+    // failure
+});
+```
+
+### Signature, encryption and decryption
+
+The normal operations: signature, encryption and decryption require
+no modifications.
+
+```js
+var openpgp = require('openpgp');
+
+var keyData = '-----BEGIN PGP PUBLIC KEY BLOCK ... END PGP PUBLIC KEY BLOCK-----';
+var key = openpgp.key.readArmored(keyData);
+
+openpgp.encrypt({publicKeys: key.keys, data: 'Hello, World!'}).then(function(msg) {
+    // success
+}).catch(function(error) {
+    // failure
+});
+```
+
+## Possible improvements
+
+*   The dependency with AES library can be eliminated, a suitable AES decrypt
+    function is provided. It is only used by the wrap and unwrap functions
+    in the crypto/rfc3394.js file.
+
+## Note
+
+Although the example uses the same value to generate the main key, and
+the subkey, it is a recommended practice to use different keys.
+The main key is used for signature and the subkeys are used for encryption.
+
+## Resources
+
+*   Elliptic Curve Cryptography (ECC) in OpenPGP [RFC 6637](http://www.ietf.org/rfc/rfc6637.txt)
+*   OpenPGP Message Format [RFC 4880](http://www.ietf.org/rfc/rfc4880.txt)
+*   Advanced Encryption Standard (AES) Key Wrap Algorithm [RFC 3394](http://www.ietf.org/rfc/rfc3394.txt)
+*   A JavaScript component for the Advanced Encryption Standard (AES) [AES](https://github.com/cryptocoinjs/aes)
+*   Fast elliptic-curve cryptography in a plain javascript implementation [Elliptic](https://github.com/indutny/elliptic/)