Class: OpenSSL::Engine
- Inherits:
-
Object
- Object
- OpenSSL::Engine
- Defined in:
- ossl_engine.c,
ossl_engine.c
Overview
This class is the access to openssl’s ENGINE cryptographic module implementation.
See also, www.openssl.org/docs/crypto/engine.html
Defined Under Namespace
Classes: EngineError
Class Method Summary collapse
-
.by_id ⇒ Object
call-seq: by_id(name) -> engine.
-
.OpenSSL::Engine.cleanup ⇒ Object
It is only necessary to run cleanup when engines are loaded via OpenSSL::Engine.load.
-
.engines ⇒ Object
Returns an array of currently loaded engines.
-
.load ⇒ Object
call-seq: load(enginename = nil).
Instance Method Summary collapse
-
#cipher ⇒ Object
call-seq: engine.cipher(name) -> OpenSSL::Cipher.
-
#cmds ⇒ Object
Returns an array of command definitions for the current engine.
-
#ctrl_cmd ⇒ Object
call-seq: engine.ctrl_cmd(command, value = nil) -> engine.
-
#digest ⇒ Object
call-seq: engine.digest(name) -> OpenSSL::Digest.
-
#finish ⇒ Object
Releases all internal structural references for this engine.
-
#id ⇒ Object
Get the id for this engine.
-
#inspect ⇒ Object
Pretty print this engine.
-
#load_private_key ⇒ Object
call-seq: engine.load_private_key(id = nil, data = nil) -> OpenSSL::PKey.
-
#load_public_key ⇒ Object
call-seq: engine.load_public_key(id = nil, data = nil) -> OpenSSL::PKey.
-
#name ⇒ Object
Get the descriptive name for this engine.
-
#set_default ⇒ Object
call-seq: engine.set_default(flag).
Class Method Details
.by_id ⇒ Object
call-seq:
by_id(name) -> engine
Fetch the engine as specified by the id
String
OpenSSL::Engine.by_id("openssl")
=> #<OpenSSL::Engine id="openssl" name="Software engine support">
See OpenSSL::Engine.engines for the currently loaded engines
194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 |
# File 'ossl_engine.c', line 194
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;
}
|
.OpenSSL::Engine.cleanup ⇒ Object
It is only necessary to run cleanup when engines are loaded via OpenSSL::Engine.load. However, running cleanup before exit is recommended.
See also, www.openssl.org/docs/crypto/engine.html
150 151 152 153 154 155 156 157 |
# File 'ossl_engine.c', line 150
static VALUE
ossl_engine_s_cleanup(VALUE self)
{
#if defined(HAVE_ENGINE_CLEANUP)
ENGINE_cleanup();
#endif
return Qnil;
}
|
.engines ⇒ Object
Returns an array of currently loaded engines.
163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 |
# File 'ossl_engine.c', line 163
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;
}
|
.load ⇒ Object
call-seq:
load(enginename = nil)
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.
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 |
# File 'ossl_engine.c', line 71
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 */
}
|
Instance Method Details
#cipher ⇒ Object
call-seq:
engine.cipher(name) -> OpenSSL::Cipher
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>
298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 |
# File 'ossl_engine.c', line 298
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 ⇒ Object
Returns an array of command definitions for the current engine
497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 |
# File 'ossl_engine.c', line 497
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 ⇒ Object
call-seq:
engine.ctrl_cmd(command, value = nil) -> engine
Send the given command
to this engine.
Raises an EngineError if the command
fails.
463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 |
# File 'ossl_engine.c', line 463
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 ⇒ Object
call-seq:
engine.digest(name) -> OpenSSL::Digest
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’
337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 |
# File 'ossl_engine.c', line 337
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 ⇒ Object
Releases all internal structural references for this engine.
May raise an EngineError if the engine is unavailable
270 271 272 273 274 275 276 277 278 279 |
# File 'ossl_engine.c', line 270
static VALUE
ossl_engine_finish(VALUE self)
{
ENGINE *e;
GetEngine(self, e);
if(!ENGINE_finish(e)) ossl_raise(eEngineError, NULL);
return Qnil;
}
|
#id ⇒ Object
238 239 240 241 242 243 244 |
# File 'ossl_engine.c', line 238
static VALUE
ossl_engine_get_id(VALUE self)
{
ENGINE *e;
GetEngine(self, e);
return rb_str_new2(ENGINE_get_id(e));
}
|
#inspect ⇒ Object
Pretty print this engine
523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 |
# File 'ossl_engine.c', line 523
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;
}
|
#load_private_key ⇒ Object
call-seq:
engine.load_private_key(id = nil, data = nil) -> OpenSSL::PKey
Loads the given private key by id
and data
.
An EngineError is raised of the OpenSSL::PKey is unavailable.
369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 |
# File 'ossl_engine.c', line 369
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 ⇒ Object
call-seq:
engine.load_public_key(id = nil, data = nil) -> OpenSSL::PKey
Loads the given private key by id
and data
.
An EngineError is raised of the OpenSSL::PKey is unavailable.
403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 |
# File 'ossl_engine.c', line 403
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 ⇒ Object
256 257 258 259 260 261 262 |
# File 'ossl_engine.c', line 256
static VALUE
ossl_engine_get_name(VALUE self)
{
ENGINE *e;
GetEngine(self, e);
return rb_str_new2(ENGINE_get_name(e));
}
|
#set_default ⇒ Object
call-seq:
engine.set_default(flag)
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>
442 443 444 445 446 447 448 449 450 451 452 |
# File 'ossl_engine.c', line 442
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;
}
|