class 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
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); if(!(e = ENGINE_by_id(RSTRING_PTR(id)))) ossl_raise(eEngineError, NULL); WrapEngine(klass, 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; }
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; }
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)){ /* 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); WrapEngine(klass, obj, e); rb_ary_push(ary, obj); } return ary; }
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
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); }
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; }
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; }
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); }
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; }
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)); }
Pretty print this engine
static VALUE ossl_engine_inspect(VALUE self) { VALUE str; const char *cname = rb_class2name(rb_obj_class(self)); str = rb_str_new2("#<"); rb_str_cat2(str, cname); rb_str_cat2(str, " id=\""); rb_str_append(str, ossl_engine_get_id(self)); rb_str_cat2(str, "\" name=\""); rb_str_append(str, ossl_engine_get_name(self)); rb_str_cat2(str, "\">"); return str; }
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; }
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); }
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 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; }