Merge pull request #15 from andogro/ag-README-edits

Minor README modifications, added environment variables section.

Author: andogro

README.md

@@ -5,9 +5,7 @@
 A pairing-based threshold cryptosystem for collaborative decryption and
 signatures.
 
-Provides constructors for encrypted message handling within a public key
-encryption system. It utilizes the pairing elliptic curve library to create
-and enable reconstruction of public and private key shares.
+The `threshold_crypto` crate provides constructors for encrypted message handling. It utilizes the [`pairing`](https://crates.io/crates/pairing) elliptic curve library to create and enable reconstruction of public and private key shares.
 
 In a network environment, messages are signed and encrypted, and key and
 signature shares are distributed to network participants. A message can be
@@ -48,7 +46,7 @@ fn main() {
 }
 ```
 
-### More Examples
+### Examples
 
 Run examples from the [`examples`](examples) directory using:
 
@@ -60,31 +58,37 @@ Also see the
 [distributed_key_generation](https://github.com/poanetwork/threshold_crypto/blob/d81953b55d181311c2a4eed2b6c34059fcf3fdae/src/poly.rs#L967)
 test.
 
-## More Details
+### Environment Variables
 
-The basic usage outline is: choose a threshold value t, create a key set, then
-distribute N secret key shares among the participants and publish the public
-master key. A third party can now encrypt a message to the public master key
+[`MLOCK_SECRETS`](https://github.com/poanetwork/threshold_crypto/blob/master/src/lib.rs#L51): Sets whether or not the Unix syscall [`mlock`](http://man7.org/linux/man-pages/man2/mlock.2.html) or WinAPI function [`VirtualLock`](https://msdn.microsoft.com/en-us/library/windows/desktop/aa366895(v=vs.85).aspx) is called on portions of memory containing secret values. This option is enabled by default (`MLOCK_SECRETS=true`). Disabling memory locking (`MLOCK_SECRETS=false`) allows secret values to be copied to disk, where they will not be zeroed on drop and may persist indefinitely. **Disabling memory locking should only be done in development and testing.** 
+
+Disabling memory locking is useful because it removes the possibility of tests failing due to reaching the testing system's locked memory limit. For example, if your crate uses `threshold_crypto` and you write a test that maintains hundreds or thousands of secrets in memory simultaneously, you run the risk of reaching your system's allowed number of locked pages, which will cause this library to fail.
+
+## Application Details
+
+The basic usage outline is: 
+* choose a threshold value `t`
+* create a key set
+* distribute `N` secret key shares among the participants
+* publish the public master key 
+
+A third party can now encrypt a message to the public master key
 and any set of `t + 1` participants *(but no fewer!)* can collaborate to
-decrypt it. Also, any `t + 1` participants can collaborate to sign a message,
-producing a signature that can be verified against the public master key.
+decrypt it. Also, any set of `t + 1` participants can collaborate to sign a message,
+producing a signature that is verifiable with the public master key.
 
-This cryptosystem has the property that signatures are unique, i.e.
-independent of which particular participants produced it. If `S1` and `S2` are
+In this system, a signature is unique and independent of  
+the set of participants that produced it. If `S1` and `S2` are
 signatures for the same message, produced by two different sets of `t + 1`
-secret key share holders each, then they won't just both be valid, but in fact
-equal. This is useful in some applications, for example it allows using the
-signature of a message as a pseudorandom number that is unknown to anyone
-until `t + 1` participants agree to reveal it.
-
-In its simplest form, threshold cryptography requires a trusted dealer who
-produces the secret key shares and distributes them. However, there are ways
-to produce the keys themselves in a way that guarantees that nobody except the
-corresponding participant knows their secret in the end, and this crate
+secret key share holders, both signatures will be valid AND
+equal. This is useful in some applications, for example a message signature can serve as a pseudorandom number unknown to anyone until `t + 1` participants agree to reveal it.
+
+In its simplest form, threshold_crypto requires a trusted dealer to
+produce and distribute the secret key shares. However, keys can be produced so that only the corresponding participant knows their secret in the end.  This crate
 includes the basic tools to implement such a *Distributed Key Generation*
 scheme.
 
-One major application for this library is within distributed networks that
+A major application for this library is within a distributed network that
 must tolerate up to `t` adversarial (malicious or faulty) nodes. Because `t +
 1` nodes are required to sign or reveal information, messages can be trusted
 by third-parties as representing the consensus of the network.

examples/README.md

@@ -1,5 +1,11 @@
 # Examples
 
+Run examples using:
+
+```
+$ MLOCK_SECRETS=false cargo run --example <example name>
+```
+
 - [`Public-Key Cryptography`](basic_pkc.rs) - Demonstrates how to generate a
 random secret-key and corresponding public-key, sign some bytes using a
 secret-key, validate the signature for some bytes using a public-key, encrypt