Module: OpenSSL

Defined in:
lib/openssl/bn.rb,
lib/openssl.rb,
lib/openssl/ssl.rb,
lib/openssl/hmac.rb,
lib/openssl/x509.rb,
lib/openssl/pkcs5.rb,
lib/openssl/cipher.rb,
lib/openssl/config.rb,
lib/openssl/digest.rb,
lib/openssl/marshal.rb,
lib/openssl/version.rb,
ossl.c,
ossl_bn.c,
ossl_ts.c,
ossl_kdf.c,
ossl_ssl.c,
ossl_asn1.c,
ossl_hmac.c,
ossl_ocsp.c,
ossl_pkey.c,
ossl_rand.c,
ossl_x509.c,
ossl_pkcs7.c,
ossl_cipher.c,
ossl_config.c,
ossl_digest.c,
ossl_engine.c,
ossl_pkcs12.c,
ossl_x509crl.c,
ossl_x509ext.c,
ossl_x509req.c,
ossl_x509attr.c,
ossl_x509cert.c,
ossl_x509name.c,
ossl_x509store.c,
ossl_ssl_session.c,
ossl_x509revoked.c,
ossl_ns_spki.c

Overview

Ruby-space definitions to add DER (de)serialization to classes

Info

'OpenSSL for Ruby 2' project Copyright (C) 2002 Michal Rokos <[email protected]> All rights reserved.

Licence

This program is licensed under the same licence as Ruby. (See the file 'LICENCE'.) ++

Defined Under Namespace

Modules: ASN1, Buffering, ExtConfig, KDF, Marshal, Netscape, OCSP, PKCS5, PKey, Random, SSL, X509 Classes: BN, BNError, Cipher, Config, ConfigError, Digest, Engine, HMAC, HMACError, OpenSSLError, PKCS12, PKCS7, Timestamp

Constant Summary collapse

VERSION =
"2.2.0"
OPENSSL_VERSION =

Version of OpenSSL the ruby OpenSSL extension was built with

rb_str_new2(OPENSSL_VERSION_TEXT)
OPENSSL_LIBRARY_VERSION =
rb_str_new2(SSLeay_version(SSLEAY_VERSION))
OPENSSL_VERSION_NUMBER =

Version number of OpenSSL the ruby OpenSSL extension was built with (base 16)

INT2NUM(OPENSSL_VERSION_NUMBER)
OPENSSL_FIPS =
#ifdef OPENSSL_FIPS
		    Qtrue
#else
		    Qfalse
#endif

Class Method Summary collapse

Class Method Details

.debugObject


379
380
381
382
383
# File 'ossl.c', line 379

static VALUE
ossl_debug_get(VALUE self)
{
    return dOSSL;
}

.debug=(boolean) ⇒ Boolean

Turns on or off debug mode. With debug mode, all erros added to the OpenSSL error queue will be printed to stderr.

Returns:

  • (Boolean)

392
393
394
395
396
397
398
# File 'ossl.c', line 392

static VALUE
ossl_debug_set(VALUE self, VALUE val)
{
    dOSSL = RTEST(val) ? Qtrue : Qfalse;

    return val;
}

.Digest(name) ⇒ Object

Returns a Digest subclass by name

require 'openssl'

OpenSSL::Digest("MD5")
# => OpenSSL::Digest::MD5

Digest("Foo")
# => NameError: wrong constant name Foo

67
68
69
# File 'lib/openssl/digest.rb', line 67

def Digest(name)
  OpenSSL::Digest.const_get(name)
end

.errorsArray

See any remaining errors held in queue.

Any errors you see here are probably due to a bug in Ruby's OpenSSL implementation.

Returns:

  • (Array)

340
341
342
343
344
345
346
347
348
349
350
351
352
# File 'ossl.c', line 340

VALUE
ossl_get_errors(VALUE _)
{
    VALUE ary;
    long e;

    ary = rb_ary_new();
    while ((e = ERR_get_error()) != 0){
        rb_ary_push(ary, rb_str_new2(ERR_error_string(e, NULL)));
    }

    return ary;
}

.fips_modeObject


404
405
406
407
408
409
410
411
412
413
414
415
# File 'ossl.c', line 404

static VALUE
ossl_fips_mode_get(VALUE self)
{

#ifdef OPENSSL_FIPS
    VALUE enabled;
    enabled = FIPS_mode() ? Qtrue : Qfalse;
    return enabled;
#else
    return Qfalse;
#endif
}

.fips_mode=(boolean) ⇒ Boolean

Turns FIPS mode on or off. Turning on FIPS mode will obviously only have an effect for FIPS-capable installations of the OpenSSL library. Trying to do so otherwise will result in an error.

Examples

OpenSSL.fips_mode = true   # turn FIPS mode on
OpenSSL.fips_mode = false  # and off again

Returns:

  • (Boolean)

429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
# File 'ossl.c', line 429

static VALUE
ossl_fips_mode_set(VALUE self, VALUE enabled)
{

#ifdef OPENSSL_FIPS
    if (RTEST(enabled)) {
	int mode = FIPS_mode();
	if(!mode && !FIPS_mode_set(1)) /* turning on twice leads to an error */
	    ossl_raise(eOSSLError, "Turning on FIPS mode failed");
    } else {
	if(!FIPS_mode_set(0)) /* turning off twice is OK */
	    ossl_raise(eOSSLError, "Turning off FIPS mode failed");
    }
    return enabled;
#else
    if (RTEST(enabled))
	ossl_raise(eOSSLError, "This version of OpenSSL does not support FIPS mode");
    return enabled;
#endif
}

.fixed_length_secure_compare(string, string) ⇒ Boolean

Constant time memory comparison for fixed length strings, such as results of HMAC calculations.

Returns true if the strings are identical, false if they are of the same length but not identical. If the length is different, ArgumentError is raised.

Returns:

  • (Boolean)

621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
# File 'ossl.c', line 621

static VALUE
ossl_crypto_fixed_length_secure_compare(VALUE dummy, VALUE str1, VALUE str2)
{
    const unsigned char *p1 = (const unsigned char *)StringValuePtr(str1);
    const unsigned char *p2 = (const unsigned char *)StringValuePtr(str2);
    long len1 = RSTRING_LEN(str1);
    long len2 = RSTRING_LEN(str2);

    if (len1 != len2) {
        ossl_raise(rb_eArgError, "inputs must be of equal length");
    }

    switch (CRYPTO_memcmp(p1, p2, len1)) {
        case 0:	return Qtrue;
        default: return Qfalse;
    }
}

.mem_check_startnil

Calls CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_ON). Starts tracking memory allocations. See also OpenSSL.print_mem_leaks.

This is available only when built with a capable OpenSSL and –enable-debug configure option.

Returns:

  • (nil)

464
465
466
467
468
469
# File 'ossl.c', line 464

static VALUE
mem_check_start(VALUE self)
{
	CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_ON);
	return Qnil;
}

For debugging the Ruby/OpenSSL library. Calls CRYPTO_mem_leaks_fp(stderr). Prints detected memory leaks to standard error. This cleans the global state up thus you cannot use any methods of the library after calling this.

Returns true if leaks detected, false otherwise.

This is available only when built with a capable OpenSSL and –enable-debug configure option.

Example

OpenSSL.mem_check_start
NOT_GCED = OpenSSL::PKey::RSA.new(256)

END {
  GC.start
  OpenSSL.print_mem_leaks # will print the leakage
}

493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
# File 'ossl.c', line 493

static VALUE
print_mem_leaks(VALUE self)
{
#if OPENSSL_VERSION_NUMBER >= 0x10100000
    int ret;
#endif

#ifndef HAVE_RB_EXT_RACTOR_SAFE
    // for Ruby 2.x
    void ossl_bn_ctx_free(void); // ossl_bn.c
    ossl_bn_ctx_free();
#endif

#if OPENSSL_VERSION_NUMBER >= 0x10100000
    ret = CRYPTO_mem_leaks_fp(stderr);
    if (ret < 0)
	ossl_raise(eOSSLError, "CRYPTO_mem_leaks_fp");
    return ret ? Qfalse : Qtrue;
#else
    CRYPTO_mem_leaks_fp(stderr);
    return Qnil;
#endif
}

.secure_compare(a, b) ⇒ Object

call-seq:

OpenSSL.secure_compare(string, string) -> boolean

Constant time memory comparison. Inputs are hashed using SHA-256 to mask the length of the secret. Returns true if the strings are identical, false otherwise.


33
34
35
36
37
# File 'lib/openssl.rb', line 33

def self.secure_compare(a, b)
  hashed_a = OpenSSL::Digest.digest('SHA256', a)
  hashed_b = OpenSSL::Digest.digest('SHA256', b)
  OpenSSL.fixed_length_secure_compare(hashed_a, hashed_b) && a == b
end