From af211f63c0e3327362c1b431362cf8a4271b6cf8 Mon Sep 17 00:00:00 2001
From: Sanjana Rajan <srajan1@stanford.edu>
Date: Fri, 17 Mar 2017 16:54:34 -0700
Subject: [PATCH] update README to demonstrate detached signature use, some
 documentation fixes

---
 README.md        | 40 ++++++++++++++++++++++++----------------
 src/cleartext.js |  2 +-
 src/openpgp.js   |  3 ++-
 src/signature.js |  2 +-
 4 files changed, 28 insertions(+), 19 deletions(-)

diff --git a/README.md b/README.md
index 4354ae3c..b65d1a1b 100644
--- a/README.md
+++ b/README.md
@@ -185,33 +185,41 @@ openpgp.verify(options).then(function(verified) {
 });
 ```
 
-#### Create and verify *detached* signatures for binary data
+#### Create and verify *detached* signatures
 
 ```js
-var content, detachedSig, validity;
+var options, cleartext, detachedSig, validity;
 
 var pubkey = '-----BEGIN PGP PUBLIC KEY BLOCK ... END PGP PUBLIC KEY BLOCK-----';
 var privkey = '-----BEGIN PGP PRIVATE KEY BLOCK ... END PGP PRIVATE KEY BLOCK-----';
 ```
 
 ```js
-content = 'Hello, World!';                               // input as String
-var privateKeys = openpgp.key.readArmored(privkey).keys; // for signing
-var bytes = openpgp.util.str2Uint8Array(content);        // convert text to binary
-var message = openpgp.message.fromBinary(bytes);
-var signedMessage = message.sign(privateKeys);
-var signature = signedMessage.packets.filterByTag(openpgp.enums.packet.signature);
-var armoredMessage = openpgp.armor.encode(openpgp.enums.armor.message, signature.write());
-armoredMessage = armoredMessage.replace('-----BEGIN PGP MESSAGE-----\r\n', '-----BEGIN PGP SIGNATURE-----\r\n');
-armoredMessage = armoredMessage.replace('-----END PGP MESSAGE-----\r\n', '-----END PGP SIGNATURE-----\r\n');
-detachedSig = armoredMessage; // '-----BEGIN PGP SIGNATURE ... END PGP SIGNATURE-----'
+options = {
+    data: 'Hello, World!',                             // input as String (or Uint8Array)
+    privateKeys: openpgp.key.readArmored(privkey).keys, // for signing
+    detached: true
+};
+
+openpgp.sign(options).then(function(signed) {
+    cleartext = signed.data;
+    detachedSig = signed.signature;
+});
 ```
 
 ```js
-var publicKeys = openpgp.key.readArmored(pubkey).keys; // for verifying signatures
-var msg = openpgp.message.readSignedContent(content, detachedSig);
-var result = msg.verify(publicKeys);
-validity = result[0].valid; // true
+options = {
+    message: openpgp.cleartext.readArmored(cleartext), // parse armored message
+    signature: openpgp.signature.readArmored(detachedSig), // parse detached signature
+    publicKeys: openpgp.key.readArmored(pubkey).keys   // for verification
+};
+
+openpgp.verify(options).then(function(verified) {
+    validity = verified.signatures[0].valid; // true
+    if (validity) {
+        console.log('signed by key id ' + verified.signatures[0].keyid.toHex());
+    }
+});
 ```
 
 ### Documentation
diff --git a/src/cleartext.js b/src/cleartext.js
index 21a91a7f..e9ab668e 100644
--- a/src/cleartext.js
+++ b/src/cleartext.js
@@ -36,7 +36,7 @@ import * as sigModule from './signature.js';
  * @classdesc Class that represents an OpenPGP cleartext signed message.
  * See {@link http://tools.ietf.org/html/rfc4880#section-7}
  * @param  {String}     text       The cleartext of the signed message
- * @param  {module:Signature} signature       The detached signature or an empty signature if message not yet signed
+ * @param  {module:signature} signature       The detached signature or an empty signature if message not yet signed
  */
 
 export function CleartextMessage(text, signature) {
diff --git a/src/openpgp.js b/src/openpgp.js
index 1a55187a..e3ad9404 100644
--- a/src/openpgp.js
+++ b/src/openpgp.js
@@ -114,7 +114,7 @@ export function generateKey({ userIds=[], passphrase, numBits=2048, unlocked=fal
 }
 
 /**
- * Generates a new OpenPGP key pair. Currently only supports RSA keys. Primary and subkey will be of same type.
+ * Reformats signature packets for a key and rewraps key object.
  * @param  {Array<Object>} userIds   array of user IDs e.g. [{ name:'Phil Zimmermann', email:'phil@openpgp.org' }]
  * @param  {String} passphrase       (optional) The passphrase used to encrypt the resulting private key
  * @param  {Boolean} unlocked        (optional) If the returned secret part of the generated key is unlocked
@@ -272,6 +272,7 @@ export function decrypt({ message, privateKey, publicKeys, sessionKey, password,
  * @param  {String} data                        cleartext input to be signed
  * @param  {Key|Array<Key>} privateKeys         array of keys or single key with decrypted secret key data to sign cleartext
  * @param  {Boolean} armor                      (optional) if the return value should be ascii armored or the message object
+ * @param  {Boolean} detached                   (optional) if the return value should contain a detached signature
  * @return {Promise<Object>}                    signed cleartext in the form:
  *                                                {data: ASCII armored message if 'armor' is true,
  *                                                message: full Message object if 'armor' is false, signature: detached signature if 'detached' is true}
diff --git a/src/signature.js b/src/signature.js
index 69ccf58d..276201a0 100644
--- a/src/signature.js
+++ b/src/signature.js
@@ -55,7 +55,7 @@ Signature.prototype.armor = function() {
 /**
  * reads an OpenPGP armored signature and returns a signature object
  * @param {String} armoredText text to be parsed
- * @return {module:signature~Signature} new signature object
+ * @return {Signature} new signature object
  * @static
  */
 export function readArmored(armoredText) {