# module OpenSSL::Random

### Public Class Methods

egd(filename) → true click to toggle source

Same as `::egd_bytes` but queries 255 bytes by default.

    static VALUE
    ossl_rand_egd(VALUE self, VALUE filename)
    {
        rb_check_safe_obj(filename);

        if (RAND_egd(StringValueCStr(filename)) == -1) {
            ossl_raise(eRandomError, NULL);
        }
        return Qtrue;
    }

egd_bytes(filename, length) → true click to toggle source

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)
    {
        int n = NUM2INT(len);

        rb_check_safe_obj(filename);

        if (RAND_egd_bytes(StringValueCStr(filename), n) == -1) {
            ossl_raise(eRandomError, NULL);
        }
        return Qtrue;
    }

load_random_file(filename) → true click to toggle source

Reads bytes from `filename` and adds them to the PRNG.

    static VALUE
    ossl_rand_load_file(VALUE self, VALUE filename)
    {
        rb_check_safe_obj(filename);

        if(!RAND_load_file(StringValueCStr(filename), -1)) {
            ossl_raise(eRandomError, NULL);
        }
        return Qtrue;
    }

pseudo_bytes(length) → string click to toggle source

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)
    {
        VALUE str;
        int n = NUM2INT(len);

        str = rb_str_new(0, n);
        if (RAND_pseudo_bytes((unsigned char *)RSTRING_PTR(str), n) < 1) {
            ossl_raise(eRandomError, NULL);
        }

        return str;
    }

add(str, entropy) → self click to toggle source

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, 0.0)
    OpenSSL::Random.seed(ary.join)

    static VALUE
    ossl_rand_add(VALUE self, VALUE str, VALUE entropy)
    {
        StringValue(str);
        RAND_add(RSTRING_PTR(str), RSTRING_LENINT(str), NUM2DBL(entropy));

        return self;
    }

random_bytes(length) → string click to toggle source

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)
    {
        VALUE str;
        int n = NUM2INT(len);
        int ret;

        str = rb_str_new(0, n);
        ret = RAND_bytes((unsigned char *)RSTRING_PTR(str), n);
        if (ret == 0) {
            ossl_raise(eRandomError, "RAND_bytes");
        } else if (ret == -1) {
            ossl_raise(eRandomError, "RAND_bytes is not supported");
        }

        return str;
    }

seed(str) → str click to toggle source

`::seed` is equivalent to ::add where `entropy` is length of `str`.

    static VALUE
    ossl_rand_seed(VALUE self, VALUE str)
    {
        StringValue(str);
        RAND_seed(RSTRING_PTR(str), RSTRING_LENINT(str));

        return str;
    }

status? → true | false click to toggle source

Return true if the PRNG has been seeded with enough data, false otherwise.

    static VALUE
    ossl_rand_status(VALUE self)
    {
        return RAND_status() ? Qtrue : Qfalse;
    }

write_random_file(filename) → true click to toggle source

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)
    {
        rb_check_safe_obj(filename);

        if (RAND_write_file(StringValueCStr(filename)) == -1) {
            ossl_raise(eRandomError, NULL);
        }
        return Qtrue;
    }