Class: OpenSSL::Engine (Ruby 2.3.2)
Description: Class : OpenSSL::Engine - Ruby 2.3.2

- Home
- Core 2.3.2
- Std-lib 2.3.2
- Downloads

Support for the Ruby 2.3 series has ended. See here for reference.

### Home Classes Methods

### In Files

- openssl/ossl.c

### Parent

Object

### Namespace

- CLASS OpenSSL::Engine::EngineError

### Methods

- ::by_id
- ::cleanup
- ::engines
- ::load
- #cipher
- #cmds
- #ctrl_cmd
- #digest
- #finish
- #id
- #inspect
- #load_private_key
- #load_public_key
- #name
- #set_default

### Class/Module Index

Quicksearch

- Integer
- OpenSSL::ASN1
- OpenSSL::ASN1::ASN1Data
- OpenSSL::ASN1::ASN1Error
- OpenSSL::ASN1::Constructive
- OpenSSL::ASN1::ObjectId
- OpenSSL::ASN1::Primitive
- OpenSSL::BN
- OpenSSL::BNError
- OpenSSL::Buffering
- OpenSSL::Cipher
- OpenSSL::Cipher::Cipher
- OpenSSL::Cipher::CipherError
- OpenSSL::Config
- OpenSSL::ConfigError
- OpenSSL::Digest
- OpenSSL::Digest::DigestError
- OpenSSL::Engine
- OpenSSL::Engine::EngineError
- OpenSSL::ExtConfig
- OpenSSL::HMAC
- OpenSSL::HMACError
- OpenSSL::Netscape
- OpenSSL::Netscape::SPKI
- OpenSSL::Netscape::SPKIError
- OpenSSL::OCSP
- OpenSSL::OCSP::BasicResponse
- OpenSSL::OCSP::CertificateId
- OpenSSL::OCSP::OCSPError
- OpenSSL::OCSP::Request
- OpenSSL::OCSP::Response
- OpenSSL::OpenSSLError
- OpenSSL::PKCS12
- OpenSSL::PKCS12::PKCS12Error
- OpenSSL::PKCS5
- OpenSSL::PKCS5::PKCS5Error
- OpenSSL::PKCS7
- OpenSSL::PKCS7::PKCS7Error
- OpenSSL::PKCS7::RecipientInfo
- OpenSSL::PKCS7::SignerInfo
- OpenSSL::PKey
- OpenSSL::PKey::DH
- OpenSSL::PKey::DHError
- OpenSSL::PKey::DSA
- OpenSSL::PKey::DSAError
- OpenSSL::PKey::EC
- OpenSSL::PKey::EC::Group
- OpenSSL::PKey::EC::Group::Error
- OpenSSL::PKey::EC::Point
- OpenSSL::PKey::EC::Point::Error
- OpenSSL::PKey::ECError
- OpenSSL::PKey::PKey
- OpenSSL::PKey::PKeyError
- OpenSSL::PKey::RSA
- OpenSSL::PKey::RSAError
- OpenSSL::Random
- OpenSSL::Random::RandomError
- OpenSSL::SSL
- OpenSSL::SSL::SSLContext
- OpenSSL::SSL::SSLContext::ExtConfig
- OpenSSL::SSL::SSLError
- OpenSSL::SSL::SSLErrorWaitReadable
- OpenSSL::SSL::SSLErrorWaitWritable
- OpenSSL::SSL::SSLServer
- OpenSSL::SSL::SSLSocket
- OpenSSL::SSL::SSLSocket::ExtConfig
- OpenSSL::SSL::Session
- OpenSSL::SSL::Session::SessionError
- OpenSSL::SSL::SocketForwarder
- OpenSSL::X509
- OpenSSL::X509::Attribute
- OpenSSL::X509::AttributeError
- OpenSSL::X509::CRL
- OpenSSL::X509::CRLError
- OpenSSL::X509::Certificate
- OpenSSL::X509::CertificateError
- OpenSSL::X509::Extension
- OpenSSL::X509::ExtensionError
- OpenSSL::X509::ExtensionFactory
- OpenSSL::X509::Name
- OpenSSL::X509::Name::RFC2253DN
- OpenSSL::X509::NameError
- OpenSSL::X509::Request
- OpenSSL::X509::RequestError
- OpenSSL::X509::Revoked
- OpenSSL::X509::RevokedError
- OpenSSL::X509::Store
- OpenSSL::X509::StoreContext
- OpenSSL::X509::StoreError
- unknown

No matching classes.

# OpenSSL::Engine

This class is the access to openssl's ENGINE cryptographic module implementation.

See also, www.openssl.org/docs/crypto/engine.html

### Public Class Methods

by_id(name) → engine click to toggle source

Fetch the engine as specified by the `id` String

    OpenSSL::Engine.by_id("openssl")
     => #<OpenSSL::Engine id="openssl" name="Software engine support">

See ::engines for the currently loaded engines

                   static VALUE
    ossl_engine_s_by_id(VALUE klass, VALUE id)
    {
        ENGINE *e;
        VALUE obj;

        StringValue(id);
        ossl_engine_s_load(1, &id, klass);
        obj = NewEngine(klass);
        if(!(e = ENGINE_by_id(RSTRING_PTR(id))))
            ossl_raise(eEngineError, NULL);
        SetEngine(obj, e);
        if(rb_block_given_p()) rb_yield(obj);
        if(!ENGINE_init(e))
            ossl_raise(eEngineError, NULL);
        ENGINE_ctrl(e, ENGINE_CTRL_SET_PASSWORD_CALLBACK,
                    0, NULL, (void(*)(void))ossl_pem_passwd_cb);
        ERR_clear_error();

        return obj;
    }

OpenSSL::Engine.cleanup click to toggle source

It is only necessary to run cleanup when engines are loaded via ::load. However, running cleanup before exit is recommended.

See also, www.openssl.org/docs/crypto/engine.html

                   static VALUE
    ossl_engine_s_cleanup(VALUE self)
    {
    #if defined(HAVE_ENGINE_CLEANUP)
        ENGINE_cleanup();
    #endif
        return Qnil;
    }

engines() click to toggle source

Returns an array of currently loaded engines.

                   static VALUE
    ossl_engine_s_engines(VALUE klass)
    {
        ENGINE *e;
        VALUE ary, obj;

        ary = rb_ary_new();
        for(e = ENGINE_get_first(); e; e = ENGINE_get_next(e)){
            obj = NewEngine(klass);
            /* Need a ref count of two here because of ENGINE_free being
             * called internally by OpenSSL when moving to the next ENGINE
             * and by us when releasing the ENGINE reference */
            ENGINE_up_ref(e);
            SetEngine(obj, e);
            rb_ary_push(ary, obj);
        }

        return ary;
    }

load(enginename = nil) click to toggle source

This method loads engines. If `name` is nil, then all builtin engines are loaded. Otherwise, the given `name`, as a string, is loaded if available to your runtime, and returns true. If `name` is not found, then nil is returned.

                   static VALUE
    ossl_engine_s_load(int argc, VALUE *argv, VALUE klass)
    {
    #if !defined(HAVE_ENGINE_LOAD_BUILTIN_ENGINES)
        return Qnil;
    #else
        VALUE name;

        rb_scan_args(argc, argv, "01", &name);
        if(NIL_P(name)){
            ENGINE_load_builtin_engines();
            return Qtrue;
        }
        StringValue(name);
    #ifndef OPENSSL_NO_STATIC_ENGINE
    #if HAVE_ENGINE_LOAD_DYNAMIC
        OSSL_ENGINE_LOAD_IF_MATCH(dynamic);
    #endif
    #if HAVE_ENGINE_LOAD_4758CCA
        OSSL_ENGINE_LOAD_IF_MATCH(4758cca);
    #endif
    #if HAVE_ENGINE_LOAD_AEP
        OSSL_ENGINE_LOAD_IF_MATCH(aep);
    #endif
    #if HAVE_ENGINE_LOAD_ATALLA
        OSSL_ENGINE_LOAD_IF_MATCH(atalla);
    #endif
    #if HAVE_ENGINE_LOAD_CHIL
        OSSL_ENGINE_LOAD_IF_MATCH(chil);
    #endif
    #if HAVE_ENGINE_LOAD_CSWIFT
        OSSL_ENGINE_LOAD_IF_MATCH(cswift);
    #endif
    #if HAVE_ENGINE_LOAD_NURON
        OSSL_ENGINE_LOAD_IF_MATCH(nuron);
    #endif
    #if HAVE_ENGINE_LOAD_SUREWARE
        OSSL_ENGINE_LOAD_IF_MATCH(sureware);
    #endif
    #if HAVE_ENGINE_LOAD_UBSEC
        OSSL_ENGINE_LOAD_IF_MATCH(ubsec);
    #endif
    #if HAVE_ENGINE_LOAD_PADLOCK
        OSSL_ENGINE_LOAD_IF_MATCH(padlock);
    #endif
    #if HAVE_ENGINE_LOAD_CAPI
        OSSL_ENGINE_LOAD_IF_MATCH(capi);
    #endif
    #if HAVE_ENGINE_LOAD_GMP
        OSSL_ENGINE_LOAD_IF_MATCH(gmp);
    #endif
    #if HAVE_ENGINE_LOAD_GOST
        OSSL_ENGINE_LOAD_IF_MATCH(gost);
    #endif
    #if HAVE_ENGINE_LOAD_CRYPTODEV
        OSSL_ENGINE_LOAD_IF_MATCH(cryptodev);
    #endif
    #if HAVE_ENGINE_LOAD_AESNI
        OSSL_ENGINE_LOAD_IF_MATCH(aesni);
    #endif
    #endif
    #ifdef HAVE_ENGINE_LOAD_OPENBSD_DEV_CRYPTO
        OSSL_ENGINE_LOAD_IF_MATCH(openbsd_dev_crypto);
    #endif
        OSSL_ENGINE_LOAD_IF_MATCH(openssl);
        rb_warning("no such builtin loader for `%s'", RSTRING_PTR(name));
        return Qnil;
    #endif /* HAVE_ENGINE_LOAD_BUILTIN_ENGINES */
    }

### Public Instance Methods

cipher(name) → OpenSSL::Cipher click to toggle source

This returns an OpenSSL::Cipher by `name`, if it is available in this engine.

A EngineError will be raised if the cipher is unavailable.

    e = OpenSSL::Engine.by_id("openssl")
     => #<OpenSSL::Engine id="openssl" name="Software engine support">
    e.cipher("RC4")
     => #<OpenSSL::Cipher:0x007fc5cacc3048>

                   static VALUE
    ossl_engine_get_cipher(VALUE self, VALUE name)
    {
        ENGINE *e;
        const EVP_CIPHER *ciph, *tmp;
        char *s;
        int nid;

        s = StringValuePtr(name);
        tmp = EVP_get_cipherbyname(s);
        if(!tmp) ossl_raise(eEngineError, "no such cipher `%s'", s);
        nid = EVP_CIPHER_nid(tmp);
        GetEngine(self, e);
        ciph = ENGINE_get_cipher(e, nid);
        if(!ciph) ossl_raise(eEngineError, NULL);

        return ossl_cipher_new(ciph);
    }

cmds() click to toggle source

Returns an array of command definitions for the current engine

                   static VALUE
    ossl_engine_get_cmds(VALUE self)
    {
        ENGINE *e;
        const ENGINE_CMD_DEFN *defn, *p;
        VALUE ary, tmp;

        GetEngine(self, e);
        ary = rb_ary_new();
        if ((defn = ENGINE_get_cmd_defns(e)) != NULL){
            for (p = defn; p->cmd_num > 0; p++){
                tmp = rb_ary_new();
                rb_ary_push(tmp, rb_str_new2(p->cmd_name));
                rb_ary_push(tmp, rb_str_new2(p->cmd_desc));
                rb_ary_push(tmp, ossl_engine_cmd_flag_to_name(p->cmd_flags));
                rb_ary_push(ary, tmp);
            }
        }

        return ary;
    }

ctrl_cmd(command, value = nil) → engine click to toggle source

Send the given `command` to this engine.

Raises an EngineError if the `command` fails.

                   static VALUE
    ossl_engine_ctrl_cmd(int argc, VALUE *argv, VALUE self)
    {
        ENGINE *e;
        VALUE cmd, val;
        int ret;

        GetEngine(self, e);
        rb_scan_args(argc, argv, "11", &cmd, &val);
        StringValue(cmd);
        if (!NIL_P(val)) StringValue(val);
        ret = ENGINE_ctrl_cmd_string(e, RSTRING_PTR(cmd),
                                     NIL_P(val) ? NULL : RSTRING_PTR(val), 0);
        if (!ret) ossl_raise(eEngineError, NULL);

        return self;
    }

digest(name) → OpenSSL::Digest click to toggle source

This returns an OpenSSL::Digest by `name`.

Will raise an EngineError if the digest is unavailable.

    e = OpenSSL::Engine.by_id("openssl")
      #=> #<OpenSSL::Engine id="openssl" name="Software engine support">
    e.digest("SHA1")
      #=> #<OpenSSL::Digest: da39a3ee5e6b4b0d3255bfef95601890afd80709>
    e.digest("zomg")
      #=> OpenSSL::Engine::EngineError: no such digest `zomg'

                   static VALUE
    ossl_engine_get_digest(VALUE self, VALUE name)
    {
        ENGINE *e;
        const EVP_MD *md, *tmp;
        char *s;
        int nid;

        s = StringValuePtr(name);
        tmp = EVP_get_digestbyname(s);
        if(!tmp) ossl_raise(eEngineError, "no such digest `%s'", s);
        nid = EVP_MD_nid(tmp);
        GetEngine(self, e);
        md = ENGINE_get_digest(e, nid);
        if(!md) ossl_raise(eEngineError, NULL);

        return ossl_digest_new(md);
    }

finish() click to toggle source

Releases all internal structural references for this engine.

May raise an EngineError if the engine is unavailable

                   static VALUE
    ossl_engine_finish(VALUE self)
    {
        ENGINE *e;

        GetEngine(self, e);
        if(!ENGINE_finish(e)) ossl_raise(eEngineError, NULL);

        return Qnil;
    }

id() click to toggle source

Get the id for this engine

    OpenSSL::Engine.load
    OpenSSL::Engine.engines #=> [#<OpenSSL::Engine#>, ...]
    OpenSSL::Engine.engines.first.id
      #=> "rsax"

                   static VALUE
    ossl_engine_get_id(VALUE self)
    {
        ENGINE *e;
        GetEngine(self, e);
        return rb_str_new2(ENGINE_get_id(e));
    }

inspect() click to toggle source

Pretty print this engine

                   static VALUE
    ossl_engine_inspect(VALUE self)
    {
        ENGINE *e;

        GetEngine(self, e);
        return rb_sprintf("#<%"PRIsVALUE" id=\"%s\" name=\"%s\">",
                          rb_obj_class(self), ENGINE_get_id(e), ENGINE_get_name(e));
    }

load_private_key(id = nil, data = nil) → OpenSSL::PKey click to toggle source

Loads the given private key by `id` and `data`.

An EngineError is raised of the OpenSSL::PKey is unavailable.

                   static VALUE
    ossl_engine_load_privkey(int argc, VALUE *argv, VALUE self)
    {
        ENGINE *e;
        EVP_PKEY *pkey;
        VALUE id, data, obj;
        char *sid, *sdata;

        rb_scan_args(argc, argv, "02", &id, &data);
        sid = NIL_P(id) ? NULL : StringValuePtr(id);
        sdata = NIL_P(data) ? NULL : StringValuePtr(data);
        GetEngine(self, e);
    #if OPENSSL_VERSION_NUMBER < 0x00907000L
        pkey = ENGINE_load_private_key(e, sid, sdata);
    #else
        pkey = ENGINE_load_private_key(e, sid, NULL, sdata);
    #endif
        if (!pkey) ossl_raise(eEngineError, NULL);
        obj = ossl_pkey_new(pkey);
        OSSL_PKEY_SET_PRIVATE(obj);

        return obj;
    }

load_public_key(id = nil, data = nil) → OpenSSL::PKey click to toggle source

Loads the given private key by `id` and `data`.

An EngineError is raised of the OpenSSL::PKey is unavailable.

                   static VALUE
    ossl_engine_load_pubkey(int argc, VALUE *argv, VALUE self)
    {
        ENGINE *e;
        EVP_PKEY *pkey;
        VALUE id, data;
        char *sid, *sdata;

        rb_scan_args(argc, argv, "02", &id, &data);
        sid = NIL_P(id) ? NULL : StringValuePtr(id);
        sdata = NIL_P(data) ? NULL : StringValuePtr(data);
        GetEngine(self, e);
    #if OPENSSL_VERSION_NUMBER < 0x00907000L
        pkey = ENGINE_load_public_key(e, sid, sdata);
    #else
        pkey = ENGINE_load_public_key(e, sid, NULL, sdata);
    #endif
        if (!pkey) ossl_raise(eEngineError, NULL);

        return ossl_pkey_new(pkey);
    }

name() click to toggle source

Get the descriptive name for this engine

    OpenSSL::Engine.load
    OpenSSL::Engine.engines #=> [#<OpenSSL::Engine#>, ...]
    OpenSSL::Engine.engines.first.name
      #=> "RSAX engine support"

                   static VALUE
    ossl_engine_get_name(VALUE self)
    {
        ENGINE *e;
        GetEngine(self, e);
        return rb_str_new2(ENGINE_get_name(e));
    }

set_default(flag) click to toggle source

Set the defaults for this engine with the given `flag`.

These flags are used to control combinations of algorithm methods.

`flag` can be one of the following, other flags are available depending on your OS.

All flags

  0xFFFF

No flags

  0x0000

See also <openssl/engine.h>

                   static VALUE
    ossl_engine_set_default(VALUE self, VALUE flag)
    {
        ENGINE *e;
        int f = NUM2INT(flag);

        GetEngine(self, e);
        ENGINE_set_default(e, f);

        return Qtrue;
    }