summaryrefslogtreecommitdiff
path: root/ext/openssl/ossl_rand.c
diff options
context:
space:
mode:
authorzzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2014-10-03 23:51:09 +0000
committerzzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2014-10-03 23:51:09 +0000
commit27886620d85badb44c43cb962ab4960bc55cde24 (patch)
tree30827d7a2e07f943e57ffe79a9e05b7226d4b466 /ext/openssl/ossl_rand.c
parentce63c19cccc250dad14f54310b99e11e5375d24f (diff)
* ext/openssl/ossl_rand.c: [DOC] Add rdoc for method descriptions
By @vipulnsward [Fixes GH-657] https://github.com/ruby/ruby/pull/657 git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@47781 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'ext/openssl/ossl_rand.c')
-rw-r--r--ext/openssl/ossl_rand.c39
1 files changed, 37 insertions, 2 deletions
diff --git a/ext/openssl/ossl_rand.c b/ext/openssl/ossl_rand.c
index 5481296..0f92c2e 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)