File: C:/Ruby27-x64/share/doc/ruby/html/OpenSSL/Engine.html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>class OpenSSL::Engine - RDoc Documentation</title>
<script type="text/javascript">
var rdoc_rel_prefix = "../";
var index_rel_prefix = "../";
</script>
<script src="../js/navigation.js" defer></script>
<script src="../js/search.js" defer></script>
<script src="../js/search_index.js" defer></script>
<script src="../js/searcher.js" defer></script>
<script src="../js/darkfish.js" defer></script>
<link href="../css/fonts.css" rel="stylesheet">
<link href="../css/rdoc.css" rel="stylesheet">
<body id="top" role="document" class="class">
<nav role="navigation">
<div id="project-navigation">
<div id="home-section" role="region" title="Quick navigation" class="nav-section">
<h2>
<a href="../index.html" rel="home">Home</a>
</h2>
<div id="table-of-contents-navigation">
<a href="../table_of_contents.html#pages">Pages</a>
<a href="../table_of_contents.html#classes">Classes</a>
<a href="../table_of_contents.html#methods">Methods</a>
</div>
</div>
<div id="search-section" role="search" class="project-section initially-hidden">
<form action="#" method="get" accept-charset="utf-8">
<div id="search-field-wrapper">
<input id="search-field" role="combobox" aria-label="Search"
aria-autocomplete="list" aria-controls="search-results"
type="text" name="search" placeholder="Search" spellcheck="false"
title="Type to search, Up and Down to navigate, Enter to load">
</div>
<ul id="search-results" aria-label="Search Results"
aria-busy="false" aria-expanded="false"
aria-atomic="false" class="initially-hidden"></ul>
</form>
</div>
</div>
<div id="class-metadata">
<div id="parent-class-section" class="nav-section">
<h3>Parent</h3>
<p class="link"><a href="../Object.html">Object</a>
</div>
<!-- Method Quickref -->
<div id="method-list-section" class="nav-section">
<h3>Methods</h3>
<ul class="link-list" role="directory">
<li ><a href="#method-c-by_id">::by_id</a>
<li ><a href="#method-c-cleanup">::cleanup</a>
<li ><a href="#method-c-engines">::engines</a>
<li ><a href="#method-c-load">::load</a>
<li ><a href="#method-i-cipher">#cipher</a>
<li ><a href="#method-i-cmds">#cmds</a>
<li ><a href="#method-i-ctrl_cmd">#ctrl_cmd</a>
<li ><a href="#method-i-digest">#digest</a>
<li ><a href="#method-i-finish">#finish</a>
<li ><a href="#method-i-id">#id</a>
<li ><a href="#method-i-inspect">#inspect</a>
<li ><a href="#method-i-load_private_key">#load_private_key</a>
<li ><a href="#method-i-load_public_key">#load_public_key</a>
<li ><a href="#method-i-name">#name</a>
<li ><a href="#method-i-set_default">#set_default</a>
</ul>
</div>
</div>
</nav>
<main role="main" aria-labelledby="class-OpenSSL::Engine">
<h1 id="class-OpenSSL::Engine" class="class">
class OpenSSL::Engine
</h1>
<section class="description">
<p>This class is the access to openssl's ENGINE cryptographic module implementation.</p>
<p>See also, <a href="https://www.openssl.org/docs/crypto/engine.html">www.openssl.org/docs/crypto/engine.html</a></p>
</section>
<section id="5Buntitled-5D" class="documentation-section">
<section id="public-class-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Class Methods</h3>
</header>
<div id="method-c-by_id" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
OpenSSL::Engine.by_id(name) → engine
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Fetches the engine as specified by the <em>id</em> <a href="../String.html"><code>String</code></a>.</p>
<pre>OpenSSL::Engine.by_id("openssl")
=> #<OpenSSL::Engine id="openssl" name="Software engine support"></pre>
<p>See <a href="Engine.html#method-c-engines"><code>OpenSSL::Engine.engines</code></a> for the currently loaded engines.</p>
<div class="method-source-code" id="by_id-source">
<pre>static VALUE
ossl_engine_s_by_id(VALUE klass, VALUE id)
{
ENGINE *e;
VALUE obj;
StringValueCStr(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);
ossl_clear_error();
return obj;
}</pre>
</div>
</div>
</div>
<div id="method-c-cleanup" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
OpenSSL::Engine.cleanup
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>It is only necessary to run cleanup when engines are loaded via <a href="Engine.html#method-c-load"><code>OpenSSL::Engine.load</code></a>. However, running cleanup before exit is recommended.</p>
<p>Note that this is needed and works only in <a href="../OpenSSL.html"><code>OpenSSL</code></a> < 1.1.0.</p>
<div class="method-source-code" id="cleanup-source">
<pre>static VALUE
ossl_engine_s_cleanup(VALUE self)
{
#if defined(LIBRESSL_VERSION_NUMBER) || OPENSSL_VERSION_NUMBER < 0x10100000
ENGINE_cleanup();
#endif
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-c-engines" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
OpenSSL::Engine.engines → [engine, ...]
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns an array of currently loaded engines.</p>
<div class="method-source-code" id="engines-source">
<pre>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;
}</pre>
</div>
</div>
</div>
<div id="method-c-load" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
OpenSSL::Engine.load(name = nil)
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>This method loads engines. If <em>name</em> is nil, then all builtin engines are loaded. Otherwise, the given <em>name</em>, as a <a href="../String.html"><code>String</code></a>, is loaded if available to your runtime, and returns true. If <em>name</em> is not found, then nil is returned.</p>
<div class="method-source-code" id="load-source">
<pre>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;
}
StringValueCStr(name);
#ifndef OPENSSL_NO_STATIC_ENGINE
#if HAVE_ENGINE_LOAD_DYNAMIC
OSSL_ENGINE_LOAD_IF_MATCH(dynamic, DYNAMIC);
#endif
#if HAVE_ENGINE_LOAD_4758CCA
OSSL_ENGINE_LOAD_IF_MATCH(4758cca, 4758CCA);
#endif
#if HAVE_ENGINE_LOAD_AEP
OSSL_ENGINE_LOAD_IF_MATCH(aep, AEP);
#endif
#if HAVE_ENGINE_LOAD_ATALLA
OSSL_ENGINE_LOAD_IF_MATCH(atalla, ATALLA);
#endif
#if HAVE_ENGINE_LOAD_CHIL
OSSL_ENGINE_LOAD_IF_MATCH(chil, CHIL);
#endif
#if HAVE_ENGINE_LOAD_CSWIFT
OSSL_ENGINE_LOAD_IF_MATCH(cswift, CSWIFT);
#endif
#if HAVE_ENGINE_LOAD_NURON
OSSL_ENGINE_LOAD_IF_MATCH(nuron, NURON);
#endif
#if HAVE_ENGINE_LOAD_SUREWARE
OSSL_ENGINE_LOAD_IF_MATCH(sureware, SUREWARE);
#endif
#if HAVE_ENGINE_LOAD_UBSEC
OSSL_ENGINE_LOAD_IF_MATCH(ubsec, UBSEC);
#endif
#if HAVE_ENGINE_LOAD_PADLOCK
OSSL_ENGINE_LOAD_IF_MATCH(padlock, PADLOCK);
#endif
#if HAVE_ENGINE_LOAD_CAPI
OSSL_ENGINE_LOAD_IF_MATCH(capi, CAPI);
#endif
#if HAVE_ENGINE_LOAD_GMP
OSSL_ENGINE_LOAD_IF_MATCH(gmp, GMP);
#endif
#if HAVE_ENGINE_LOAD_GOST
OSSL_ENGINE_LOAD_IF_MATCH(gost, GOST);
#endif
#if HAVE_ENGINE_LOAD_CRYPTODEV
OSSL_ENGINE_LOAD_IF_MATCH(cryptodev, CRYPTODEV);
#endif
#if HAVE_ENGINE_LOAD_AESNI
OSSL_ENGINE_LOAD_IF_MATCH(aesni, AESNI);
#endif
#endif
#ifdef HAVE_ENGINE_LOAD_OPENBSD_DEV_CRYPTO
OSSL_ENGINE_LOAD_IF_MATCH(openbsd_dev_crypto, OPENBSD_DEV_CRYPTO);
#endif
OSSL_ENGINE_LOAD_IF_MATCH(openssl, OPENSSL);
rb_warning("no such builtin loader for `%"PRIsVALUE"'", name);
return Qnil;
#endif /* HAVE_ENGINE_LOAD_BUILTIN_ENGINES */
}</pre>
</div>
</div>
</div>
</section>
<section id="public-instance-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Instance Methods</h3>
</header>
<div id="method-i-cipher" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
cipher(name) → OpenSSL::Cipher
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns a new instance of <a href="Cipher.html"><code>OpenSSL::Cipher</code></a> by <em>name</em>, if it is available in this engine.</p>
<p>An <a href="Engine/EngineError.html"><code>EngineError</code></a> will be raised if the cipher is unavailable.</p>
<pre>e = OpenSSL::Engine.by_id("openssl")
=> #<OpenSSL::Engine id="openssl" name="Software engine support">
e.cipher("RC4")
=> #<OpenSSL::Cipher:0x007fc5cacc3048></pre>
<div class="method-source-code" id="cipher-source">
<pre>static VALUE
ossl_engine_get_cipher(VALUE self, VALUE name)
{
ENGINE *e;
const EVP_CIPHER *ciph, *tmp;
int nid;
tmp = EVP_get_cipherbyname(StringValueCStr(name));
if(!tmp) ossl_raise(eEngineError, "no such cipher `%"PRIsVALUE"'", name);
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);
}</pre>
</div>
</div>
</div>
<div id="method-i-cmds" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
cmds → [["name", "description", "flags"], ...]
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns an array of command definitions for the current engine</p>
<div class="method-source-code" id="cmds-source">
<pre>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;
}</pre>
</div>
</div>
</div>
<div id="method-i-ctrl_cmd" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
ctrl_cmd(command, value = nil) → engine
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Sends the given <em>command</em> to this engine.</p>
<p>Raises an <a href="Engine/EngineError.html"><code>EngineError</code></a> if the command fails.</p>
<div class="method-source-code" id="ctrl_cmd-source">
<pre>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);
ret = ENGINE_ctrl_cmd_string(e, StringValueCStr(cmd),
NIL_P(val) ? NULL : StringValueCStr(val), 0);
if (!ret) ossl_raise(eEngineError, NULL);
return self;
}</pre>
</div>
</div>
</div>
<div id="method-i-digest" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
digest(name) → OpenSSL::Digest
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns a new instance of <a href="Digest.html"><code>OpenSSL::Digest</code></a> by <em>name</em>.</p>
<p>Will raise an <a href="Engine/EngineError.html"><code>EngineError</code></a> if the digest is unavailable.</p>
<pre class="ruby"><span class="ruby-identifier">e</span> = <span class="ruby-constant">OpenSSL</span><span class="ruby-operator">::</span><span class="ruby-constant">Engine</span>.<span class="ruby-identifier">by_id</span>(<span class="ruby-string">"openssl"</span>)
<span class="ruby-comment">#=> #<OpenSSL::Engine id="openssl" name="Software engine support"></span>
<span class="ruby-identifier">e</span>.<span class="ruby-identifier">digest</span>(<span class="ruby-string">"SHA1"</span>)
<span class="ruby-comment">#=> #<OpenSSL::Digest: da39a3ee5e6b4b0d3255bfef95601890afd80709></span>
<span class="ruby-identifier">e</span>.<span class="ruby-identifier">digest</span>(<span class="ruby-string">"zomg"</span>)
<span class="ruby-comment">#=> OpenSSL::Engine::EngineError: no such digest `zomg'</span>
</pre>
<div class="method-source-code" id="digest-source">
<pre>static VALUE
ossl_engine_get_digest(VALUE self, VALUE name)
{
ENGINE *e;
const EVP_MD *md, *tmp;
int nid;
tmp = EVP_get_digestbyname(StringValueCStr(name));
if(!tmp) ossl_raise(eEngineError, "no such digest `%"PRIsVALUE"'", name);
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);
}</pre>
</div>
</div>
</div>
<div id="method-i-finish" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
finish → nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Releases all internal structural references for this engine.</p>
<p>May raise an <a href="Engine/EngineError.html"><code>EngineError</code></a> if the engine is unavailable</p>
<div class="method-source-code" id="finish-source">
<pre>static VALUE
ossl_engine_finish(VALUE self)
{
ENGINE *e;
GetEngine(self, e);
if(!ENGINE_finish(e)) ossl_raise(eEngineError, NULL);
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-i-id" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
id → string
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Gets the id for this engine.</p>
<pre class="ruby"><span class="ruby-constant">OpenSSL</span><span class="ruby-operator">::</span><span class="ruby-constant">Engine</span>.<span class="ruby-identifier">load</span>
<span class="ruby-constant">OpenSSL</span><span class="ruby-operator">::</span><span class="ruby-constant">Engine</span>.<span class="ruby-identifier">engines</span> <span class="ruby-comment">#=> [#<OpenSSL::Engine#>, ...]</span>
<span class="ruby-constant">OpenSSL</span><span class="ruby-operator">::</span><span class="ruby-constant">Engine</span>.<span class="ruby-identifier">engines</span>.<span class="ruby-identifier">first</span>.<span class="ruby-identifier">id</span>
<span class="ruby-comment">#=> "rsax"</span>
</pre>
<div class="method-source-code" id="id-source">
<pre>static VALUE
ossl_engine_get_id(VALUE self)
{
ENGINE *e;
GetEngine(self, e);
return rb_str_new2(ENGINE_get_id(e));
}</pre>
</div>
</div>
</div>
<div id="method-i-inspect" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
inspect → string
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Pretty prints this engine.</p>
<div class="method-source-code" id="inspect-source">
<pre>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));
}</pre>
</div>
</div>
</div>
<div id="method-i-load_private_key" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
load_private_key(id = nil, data = nil) → OpenSSL::PKey
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Loads the given private key identified by <em>id</em> and <em>data</em>.</p>
<p>An <a href="Engine/EngineError.html"><code>EngineError</code></a> is raised of the <a href="PKey.html"><code>OpenSSL::PKey</code></a> is unavailable.</p>
<div class="method-source-code" id="load_private_key-source">
<pre>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 : StringValueCStr(id);
sdata = NIL_P(data) ? NULL : StringValueCStr(data);
GetEngine(self, e);
pkey = ENGINE_load_private_key(e, sid, NULL, sdata);
if (!pkey) ossl_raise(eEngineError, NULL);
obj = ossl_pkey_new(pkey);
OSSL_PKEY_SET_PRIVATE(obj);
return obj;
}</pre>
</div>
</div>
</div>
<div id="method-i-load_public_key" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
load_public_key(id = nil, data = nil) → OpenSSL::PKey
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Loads the given public key identified by <em>id</em> and <em>data</em>.</p>
<p>An <a href="Engine/EngineError.html"><code>EngineError</code></a> is raised of the <a href="PKey.html"><code>OpenSSL::PKey</code></a> is unavailable.</p>
<div class="method-source-code" id="load_public_key-source">
<pre>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 : StringValueCStr(id);
sdata = NIL_P(data) ? NULL : StringValueCStr(data);
GetEngine(self, e);
pkey = ENGINE_load_public_key(e, sid, NULL, sdata);
if (!pkey) ossl_raise(eEngineError, NULL);
return ossl_pkey_new(pkey);
}</pre>
</div>
</div>
</div>
<div id="method-i-name" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
name → string
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Get the descriptive name for this engine.</p>
<pre class="ruby"><span class="ruby-constant">OpenSSL</span><span class="ruby-operator">::</span><span class="ruby-constant">Engine</span>.<span class="ruby-identifier">load</span>
<span class="ruby-constant">OpenSSL</span><span class="ruby-operator">::</span><span class="ruby-constant">Engine</span>.<span class="ruby-identifier">engines</span> <span class="ruby-comment">#=> [#<OpenSSL::Engine#>, ...]</span>
<span class="ruby-constant">OpenSSL</span><span class="ruby-operator">::</span><span class="ruby-constant">Engine</span>.<span class="ruby-identifier">engines</span>.<span class="ruby-identifier">first</span>.<span class="ruby-identifier">name</span>
<span class="ruby-comment">#=> "RSAX engine support"</span>
</pre>
<div class="method-source-code" id="name-source">
<pre>static VALUE
ossl_engine_get_name(VALUE self)
{
ENGINE *e;
GetEngine(self, e);
return rb_str_new2(ENGINE_get_name(e));
}</pre>
</div>
</div>
</div>
<div id="method-i-set_default" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
set_default(flag)
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p><a href="../Set.html"><code>Set</code></a> the defaults for this engine with the given <em>flag</em>.</p>
<p>These flags are used to control combinations of algorithm methods.</p>
<p><em>flag</em> can be one of the following, other flags are available depending on your OS.</p>
<dl class="rdoc-list label-list"><dt>All flags
<dd>
<p>0xFFFF</p>
</dd><dt>No flags
<dd>
<p>0x0000</p>
</dd></dl>
<p>See also <openssl/engine.h></p>
<div class="method-source-code" id="set_default-source">
<pre>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;
}</pre>
</div>
</div>
</div>
</section>
</section>
</main>
<footer id="validator-badges" role="contentinfo">
<p><a href="https://validator.w3.org/check/referer">Validate</a>
<p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.2.1.1.
<p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
</footer>