класс OpenSSL::Engine

Родитель:: Объект

Этот класс предоставляет доступ к реализации криптографического модуля OpenSSL ENGINE.

См. также www.openssl.org/docs/crypto/engine.html

Публичные методы класса

OpenSSL::Engine.by_id(name) → engine Показать исходный код

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;
}

Получает движок, указанный строкой id.

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

См. ::engines для получения списка загруженных движков.

OpenSSL::Engine.cleanup Показать исходный код

static VALUE
ossl_engine_s_cleanup(VALUE self)
{
#if defined(LIBRESSL_VERSION_NUMBER) || OPENSSL_VERSION_NUMBER < 0x10100000
    ENGINE_cleanup();
#endif
    return Qnil;
}

Выполнение cleanup необходимо только в том случае, если движки загружались с помощью ::load. Однако рекомендуется выполнять cleanup перед выходом из программы.

Обратите внимание, что это необходимо и работает только в OpenSSL < 1.1.0.

OpenSSL::Engine.engines → [engine, ...] Показать исходный код

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) Показать исходный код

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 */
}

Этот метод загружает движки. Если name имеет значение nil, загружаются все встроенные движки. В противном случае, если движок с заданным именем (строка) доступен в вашей среде выполнения, он загружается и возвращает true. Если name не найден, возвращается nil.

Публичные методы экземпляра

cipher(name) → OpenSSL::Cipher Показать исходный код

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);
}

Возвращает новый экземпляр OpenSSL::Cipher по имени name, если он доступен в этом движке.

Если шифр недоступен, будет выброшено исключение EngineError.

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

cmds → [["name", "description", "flags"], ...] Показать исходный код

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 Показать исходный код

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;
}

Отправляет заданную команду в этот движок.

Выбрасывает исключение EngineError, если команда выполнена неудачно.

digest(name) → OpenSSL::Digest Показать исходный код

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);
}

Возвращает новый экземпляр OpenSSL::Digest по имени name.

Вызовет исключение EngineError, если хеш-функция недоступна.

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'

finish → nil Показать исходный код

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

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

    return Qnil;
}

Освобождает все внутренние структурные ссылки для этого движка.

Может выбросить исключение EngineError, если движок недоступен

id → string Показать исходный код

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

Получает идентификатор для этого движка.

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

inspect → string Показать исходный код

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 Показать исходный код

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;
}

Загружает заданный закрытый ключ, идентифицированный по id и data.

Если OpenSSL::PKey недоступен, выбросится исключение EngineError.

load_public_key(id = nil, data = nil) → OpenSSL::PKey Показать исходный код

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);
}

Загружает заданный открытый ключ, идентифицированный по id и data.

Если OpenSSL::PKey недоступен, выбросится исключение EngineError.

name → string Показать исходный код

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

Получить описательное имя для этого движка.

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

set_default(flag) Показать исходный код

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;
}

Устанавливает значения по умолчанию для этого движка с помощью заданного flag.

Эти флаги используются для управления комбинациями алгоритмических методов.

flag может быть одним из следующих, другие флаги доступны в зависимости от вашей ОС.

Все флаги: 0xFFFF
Нет флагов: 0x0000

См. также <openssl/engine.h>

Ruby Core © 1993–2017 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.