1 files changed, 37 insertions, 2 deletions
diff --git a/ext/openssl/ossl_rand.c b/ext/openssl/ossl_rand.c
index 5481296c90..0f92c2e884 100644
--- a/ext/openssl/ossl_rand.c
+++ b/ext/openssl/ossl_rand.c
@@ -32,6 +32,7 @@ VALUE eRandomError;
  *  call-seq:
  *     seed(str) -> str
  *
+ * ::seed is equivalent to ::add where +entropy+ is length of +str+.
  */
 static VALUE
 ossl_rand_seed(VALUE self, VALUE str)
@@ -46,6 +47,19 @@ ossl_rand_seed(VALUE self, VALUE str)
  *  call-seq:
  *     add(str, entropy) -> self
  *
+ * Mixes the bytes from +str+ into the Pseudo Random Number Generator(PRNG) state.
+ * Thus, if the data from +str+ are unpredictable to an adversary, this increases the uncertainty about the state
+ * and makes the PRNG output less predictable.
+ * The +entropy+ argument is (the lower bound of) an estimate of how much randomness is contained in +str+,
+ * measured in bytes.
+ *
+ *  Example:
+ *
+ *    pid = $$
+ *    now = Time.now
+ *    ary = [now.to_i, now.nsec, 1000, pid]
+ *    OpenSSL::Random.add(ary.join("").to_s, 0.0)
+ *    OpenSSL::Random.seed(ary.join("").to_s)
  */
 static VALUE
 ossl_rand_add(VALUE self, VALUE str, VALUE entropy)
@@ -60,6 +74,7 @@ ossl_rand_add(VALUE self, VALUE str, VALUE entropy)
  *  call-seq:
  *     load_random_file(filename) -> true
  *
+ * Reads bytes from +filename+ and adds them to the PRNG.
  */
 static VALUE
 ossl_rand_load_file(VALUE self, VALUE filename)
@@ -76,6 +91,8 @@ ossl_rand_load_file(VALUE self, VALUE filename)
  *  call-seq:
  *     write_random_file(filename) -> true
  *
+ * Writes a number of random generated bytes (currently 1024) to +filename+ which can be used to initialize the PRNG by
+ * calling ::load_random_file in a later session.
  */
 static VALUE
 ossl_rand_write_file(VALUE self, VALUE filename)
@@ -89,8 +106,14 @@ ossl_rand_write_file(VALUE self, VALUE filename)
 
 /*
  *  call-seq:
- *     random_bytes(length) -> aString
+ *     -> string
+ *
+ * Generates +string+ with +length+ number of cryptographically strong pseudo-random bytes.
+ *
+ *  Example:
  *
+ *    OpenSSL::Random.random_bytes(12)
+ *    => "..."
  */
 static VALUE
 ossl_rand_bytes(VALUE self, VALUE len)
@@ -108,8 +131,17 @@ ossl_rand_bytes(VALUE self, VALUE len)
 
 /*
  *  call-seq:
- *     pseudo_bytes(length) -> aString
+ *     -> string
+ *
+ * Generates +string+ with +length+ number of pseudo-random bytes.
+ *
+ * Pseudo-random byte sequences generated by ::pseudo_bytes will be unique if they are of sufficient length,
+ * but are not necessarily unpredictable.
+ *
+ *  Example:
  *
+ *    OpenSSL::Random.pseudo_bytes(12)
+ *    => "..."
  */
 static VALUE
 ossl_rand_pseudo_bytes(VALUE self, VALUE len)
@@ -129,6 +161,7 @@ ossl_rand_pseudo_bytes(VALUE self, VALUE len)
  *  call-seq:
  *     egd(filename) -> true
  *
+ * Same as ::egd_bytes but queries 255 bytes by default.
  */
 static VALUE
 ossl_rand_egd(VALUE self, VALUE filename)
@@ -145,6 +178,8 @@ ossl_rand_egd(VALUE self, VALUE filename)
  *  call-seq:
  *     egd_bytes(filename, length) -> true
  *
+ * Queries the entropy gathering daemon EGD on socket path given by +filename+.
+ * Fetches +length+ number of bytes and uses ::add to seed the OpenSSL built-in PRNG.
  */
 static VALUE
 ossl_rand_egd_bytes(VALUE self, VALUE filename, VALUE len)