Class: OpenSSL::Engine
- Inherits:
-
Object
- Object
- OpenSSL::Engine
- Defined in:
- ext/openssl/ossl_engine.c,
ext/openssl/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
-
.OpenSSL::Engine.by_id(name) ⇒ Object
Fetches the engine as specified by the id String.
-
.OpenSSL::Engine.cleanup ⇒ Object
It is only necessary to run cleanup when engines are loaded via OpenSSL::Engine.load.
-
.OpenSSL::Engine.engines ⇒ Array
Returns an array of currently loaded engines.
-
.OpenSSL::Engine.load(name = nil) ⇒ Object
This method loads engines.
Instance Method Summary collapse
-
#cipher(name) ⇒ OpenSSL::Cipher
Returns a new instance of OpenSSL::Cipher by name, if it is available in this engine.
-
#cmds ⇒ Array
Returns an array of command definitions for the current engine.
-
#ctrl_cmd(command, value = nil) ⇒ Object
Sends the given command to this engine.
-
#digest(name) ⇒ OpenSSL::Digest
Returns a new instance of OpenSSL::Digest by name.
-
#finish ⇒ nil
Releases all internal structural references for this engine.
-
#id ⇒ String
Gets the id for this engine.
-
#inspect ⇒ String
Pretty prints this engine.
-
#load_private_key(id = nil, data = nil) ⇒ OpenSSL::PKey
Loads the given private key identified by id and data.
-
#load_public_key(id = nil, data = nil) ⇒ OpenSSL::PKey
Loads the given public key identified by id and data.
-
#name ⇒ String
Get the descriptive name for this engine.
-
#set_default(flag) ⇒ Object
Set the defaults for this engine with the given flag.
Class Method Details
.OpenSSL::Engine.by_id(name) ⇒ Object
Fetches 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.
218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 |
# File 'ext/openssl/ossl_engine.c', line 218
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;
}
|
.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.
Note that this is needed and works only in OpenSSL < 1.1.0.
172 173 174 175 176 177 178 179 |
# File 'ext/openssl/ossl_engine.c', line 172
static VALUE
ossl_engine_s_cleanup(VALUE self)
{
#if defined(LIBRESSL_VERSION_NUMBER) || OPENSSL_VERSION_NUMBER < 0x10100000
ENGINE_cleanup();
#endif
return Qnil;
}
|
.OpenSSL::Engine.engines ⇒ Array
Returns an array of currently loaded engines.
187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 |
# File 'ext/openssl/ossl_engine.c', line 187
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;
}
|
.OpenSSL::Engine.load(name = nil) ⇒ Object
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.
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 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 |
# File 'ext/openssl/ossl_engine.c', line 93
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 */
}
|
Instance Method Details
#cipher(name) ⇒ OpenSSL::Cipher
Returns a new instance of OpenSSL::Cipher by name, if it is available in this engine.
An 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>
313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 |
# File 'ext/openssl/ossl_engine.c', line 313
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);
}
|
#cmds ⇒ Array
Returns an array of command definitions for the current engine
488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 |
# File 'ext/openssl/ossl_engine.c', line 488
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) ⇒ Object
Sends the given command to this engine.
Raises an EngineError if the command fails.
454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 |
# File 'ext/openssl/ossl_engine.c', line 454
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;
}
|
#digest(name) ⇒ OpenSSL::Digest
Returns a new instance of 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’
345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 |
# File 'ext/openssl/ossl_engine.c', line 345
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);
}
|
#finish ⇒ nil
Releases all internal structural references for this engine.
May raise an EngineError if the engine is unavailable
287 288 289 290 291 292 293 294 295 296 |
# File 'ext/openssl/ossl_engine.c', line 287
static VALUE
ossl_engine_finish(VALUE self)
{
ENGINE *e;
GetEngine(self, e);
if(!ENGINE_finish(e)) ossl_raise(eEngineError, NULL);
return Qnil;
}
|
#id ⇒ String
251 252 253 254 255 256 257 |
# File 'ext/openssl/ossl_engine.c', line 251
static VALUE
ossl_engine_get_id(VALUE self)
{
ENGINE *e;
GetEngine(self, e);
return rb_str_new2(ENGINE_get_id(e));
}
|
#inspect ⇒ String
Pretty prints this engine.
516 517 518 519 520 521 522 523 524 |
# File 'ext/openssl/ossl_engine.c', line 516
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
Loads the given private key identified by id and data.
An EngineError is raised of the OpenSSL::PKey is unavailable.
371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 |
# File 'ext/openssl/ossl_engine.c', line 371
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;
}
|
#load_public_key(id = nil, data = nil) ⇒ OpenSSL::PKey
Loads the given public key identified by id and data.
An EngineError is raised of the OpenSSL::PKey is unavailable.
400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 |
# File 'ext/openssl/ossl_engine.c', line 400
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);
}
|
#name ⇒ String
271 272 273 274 275 276 277 |
# File 'ext/openssl/ossl_engine.c', line 271
static VALUE
ossl_engine_get_name(VALUE self)
{
ENGINE *e;
GetEngine(self, e);
return rb_str_new2(ENGINE_get_name(e));
}
|
#set_default(flag) ⇒ Object
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>
434 435 436 437 438 439 440 441 442 443 444 |
# File 'ext/openssl/ossl_engine.c', line 434
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;
}
|