класс OpenSSL::PKey::DH

Родитель:: OpenSSL::PKey::PKey

Реализация протокола обмена ключами Диффи-Хеллмана, основанного на дискретных логарифмах в конечных полях, на той же основе, что и DSA.

Методы доступа к параметрам Диффи-Хеллмана

Kernel#p: Простое число (объект OpenSSL::BN) параметров Диффи-Хеллмана.
DH#g: Генератор (объект OpenSSL::BN) g параметров Диффи-Хеллмана.
DH#pub_key: Открытый ключ на сессию (объект OpenSSL::BN), соответствующий закрытому ключу. Его нужно передать в #compute_key.
DH#priv_key: Закрытый ключ на сессию, объект OpenSSL::BN.

Пример обмена ключами

dh1 = OpenSSL::PKey::DH.new(2048)
der = dh1.public_key.to_der #you may send this publicly to the participating party
dh2 = OpenSSL::PKey::DH.new(der)
dh2.generate_key! #generate the per-session key pair
symm_key1 = dh1.compute_key(dh2.pub_key)
symm_key2 = dh2.compute_key(dh1.pub_key)

puts symm_key1 == symm_key2 # => true

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

generate(size [, generator]) → dh Показать исходный код

static VALUE
ossl_dh_s_generate(int argc, VALUE *argv, VALUE klass)
{
    DH *dh ;
    int g = 2;
    VALUE size, gen, obj;

    if (rb_scan_args(argc, argv, "11", &size, &gen) == 2) {
        g = NUM2INT(gen);
    }
    dh = dh_generate(NUM2INT(size), g);
    obj = dh_instance(klass, dh);
    if (obj == Qfalse) {
        DH_free(dh);
        ossl_raise(eDHError, NULL);
    }

    return obj;
}

Создаёт новый экземпляр DH с нуля, сгенерировав как частные, так и публичные компоненты.

Параметры

size — целое число, представляющее желаемый размер ключа. Ключи меньше 1024 бит следует считать небезопасными.
generator — небольшое число > 1, обычно 2 или 5.

new → dh Показать исходный код

new(string) → dh

new(size [, generator]) → dh

static VALUE
ossl_dh_initialize(int argc, VALUE *argv, VALUE self)
{
    EVP_PKEY *pkey;
    DH *dh;
    int g = 2;
    BIO *in;
    VALUE arg, gen;

    GetPKey(self, pkey);
    if(rb_scan_args(argc, argv, "02", &arg, &gen) == 0) {
      dh = DH_new();
    }
    else if (RB_INTEGER_TYPE_P(arg)) {
        if (!NIL_P(gen)) {
            g = NUM2INT(gen);
        }
        if (!(dh = dh_generate(NUM2INT(arg), g))) {
            ossl_raise(eDHError, NULL);
        }
    }
    else {
        arg = ossl_to_der_if_possible(arg);
        in = ossl_obj2bio(&arg);
        dh = PEM_read_bio_DHparams(in, NULL, NULL, NULL);
        if (!dh){
            OSSL_BIO_reset(in);
            dh = d2i_DHparams_bio(in, NULL);
        }
        BIO_free(in);
        if (!dh) {
            ossl_raise(eDHError, NULL);
        }
    }
    if (!EVP_PKEY_assign_DH(pkey, dh)) {
        DH_free(dh);
        ossl_raise(eDHError, NULL);
    }
    return self;
}

Либо генерирует экземпляр DH с нуля, либо считывает уже существующие параметры DH из string. Обратите внимание, что при чтении экземпляра DH из данных, закодированных из экземпляра DH с использованием #to_pem или #to_der, результат не будет содержать пару открытого/закрытого ключа. Необходимо сгенерировать её с помощью #generate_key! сначала.

Параметры

size — целое число, представляющее желаемый размер ключа. Ключи меньше 1024 бит следует считать небезопасными.
generator — небольшое число > 1, обычно 2 или 5.
string содержит закодированный DER или PEM ключ.

Примеры

DH.new # -> dh
DH.new(1024) # -> dh
DH.new(1024, 5) # -> dh
#Reading DH parameters
dh = DH.new(File.read('parameters.pem')) # -> dh, but no public/private key yet
dh.generate_key! # -> dh with public and private key

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

compute_key(pub_bn) → aString Показать исходный код

static VALUE
ossl_dh_compute_key(VALUE self, VALUE pub)
{
    DH *dh;
    const BIGNUM *pub_key, *dh_p;
    VALUE str;
    int len;

    GetDH(self, dh);
    DH_get0_pqg(dh, &dh_p, NULL, NULL);
    if (!dh_p)
        ossl_raise(eDHError, "incomplete DH");
    pub_key = GetBNPtr(pub);
    len = DH_size(dh);
    str = rb_str_new(0, len);
    if ((len = DH_compute_key((unsigned char *)RSTRING_PTR(str), pub_key, dh)) < 0) {
        ossl_raise(eDHError, NULL);
    }
    rb_str_set_len(str, len);

    return str;
}

Возвращает строку, содержащую общий секрет, вычисленный из значения открытого ключа другой стороны. См. DH_compute_key() для дополнительной информации.

Параметры

pub_bn — OpenSSL::BN, не экземпляр DH, возвращаемый #public_key, так как он содержит только параметры DH.

export → aString Показать исходный код

to_pem → aString

to_s → aString

static VALUE
ossl_dh_export(VALUE self)
{
    DH *dh;
    BIO *out;
    VALUE str;

    GetDH(self, dh);
    if (!(out = BIO_new(BIO_s_mem()))) {
        ossl_raise(eDHError, NULL);
    }
    if (!PEM_write_bio_DHparams(out, dh)) {
        BIO_free(out);
        ossl_raise(eDHError, NULL);
    }
    str = ossl_membio2str(out);

    return str;
}

Кодирует этот экземпляр DH в его кодировку PEM. Обратите внимание, что любые существующие сессионные открытые/закрытые ключи не будут закодированы, будет закодированы только параметры Диффи-Хеллмана.

Также алиасы: to_pem, to_s

generate_key! → self Показать исходный код

static VALUE
ossl_dh_generate_key(VALUE self)
{
    DH *dh;

    GetDH(self, dh);
    if (!DH_generate_key(dh))
        ossl_raise(eDHError, "Failed to generate key");
    return self;
}

Генерирует закрытый и открытый ключ, если закрытый ключ ещё не существует. Если этот экземпляр DH был сгенерирован из публичных параметров DH (например, путём кодирования результата #public_key), то этот метод необходимо вызвать в первую очередь, чтобы сгенерировать сессионные ключи перед выполнением фактического обмена ключами.

Пример

dh = OpenSSL::PKey::DH.new(2048)
public_key = dh.public_key #contains no private/public key yet
public_key.generate_key!
puts public_key.private? # => true

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

static VALUE
ossl_dh_initialize_copy(VALUE self, VALUE other)
{
    EVP_PKEY *pkey;
    DH *dh, *dh_other;
    const BIGNUM *pub, *priv;

    GetPKey(self, pkey);
    if (EVP_PKEY_base_id(pkey) != EVP_PKEY_NONE)
        ossl_raise(eDHError, "DH already initialized");
    GetDH(other, dh_other);

    dh = DHparams_dup(dh_other);
    if (!dh)
        ossl_raise(eDHError, "DHparams_dup");
    EVP_PKEY_assign_DH(pkey, dh);

    DH_get0_key(dh_other, &pub, &priv);
    if (pub) {
        BIGNUM *pub2 = BN_dup(pub);
        BIGNUM *priv2 = BN_dup(priv);

        if (!pub2 || priv && !priv2) {
            BN_clear_free(pub2);
            BN_clear_free(priv2);
            ossl_raise(eDHError, "BN_dup");
        }
        DH_set0_key(dh, pub2, priv2);
    }

    return self;
}

params → hash Показать исходный код

static VALUE
ossl_dh_get_params(VALUE self)
{
    DH *dh;
    VALUE hash;
    const BIGNUM *p, *q, *g, *pub_key, *priv_key;

    GetDH(self, dh);
    DH_get0_pqg(dh, &p, &q, &g);
    DH_get0_key(dh, &pub_key, &priv_key);

    hash = rb_hash_new();
    rb_hash_aset(hash, rb_str_new2("p"), ossl_bn_new(p));
    rb_hash_aset(hash, rb_str_new2("q"), ossl_bn_new(q));
    rb_hash_aset(hash, rb_str_new2("g"), ossl_bn_new(g));
    rb_hash_aset(hash, rb_str_new2("pub_key"), ossl_bn_new(pub_key));
    rb_hash_aset(hash, rb_str_new2("priv_key"), ossl_bn_new(priv_key));

    return hash;
}

Сохраняет все параметры ключа в хэш НЕБЕЗОПАСНО: КОНФИДЕНЦИАЛЬНАЯ ИНФОРМАЦИЯ МОЖЕТ УТЕЧЬ!!! Не используйте :-)) (Это ваше решение)

params_ok? → true | false Показать исходный код

static VALUE
ossl_dh_check_params(VALUE self)
{
    DH *dh;
    int codes;

    GetDH(self, dh);
    if (!DH_check(dh, &codes)) {
        return Qfalse;
    }

    return codes == 0 ? Qtrue : Qfalse;
}

Проверяет параметры Диффи-Хеллмана, связанные с этим экземпляром. Он проверяет, используется ли безопасное простое число и подходящий генератор. Если это не так, то возвращается false.

private? → true | false Показать исходный код

static VALUE
ossl_dh_is_private(VALUE self)
{
    DH *dh;
    const BIGNUM *bn;

    GetDH(self, dh);
    DH_get0_key(dh, NULL, &bn);

#if !defined(OPENSSL_NO_ENGINE)
    return (bn || DH_get0_engine(dh)) ? Qtrue : Qfalse;
#else
    return bn ? Qtrue : Qfalse;
#endif
}

Указывает, есть ли у этого экземпляра DH связанный с ним закрытый ключ или нет. Закрытый ключ можно получить с помощью DH#priv_key.

public? → true | false Показать исходный код

static VALUE
ossl_dh_is_public(VALUE self)
{
    DH *dh;
    const BIGNUM *bn;

    GetDH(self, dh);
    DH_get0_key(dh, &bn, NULL);

    return bn ? Qtrue : Qfalse;
}

Указывает, есть ли у этого экземпляра DH связанный с ним открытый ключ или нет. Открытый ключ можно получить с помощью DH#pub_key.

public_key → aDH Показать исходный код

static VALUE
ossl_dh_to_public_key(VALUE self)
{
    DH *orig_dh, *dh;
    VALUE obj;

    GetDH(self, orig_dh);
    dh = DHparams_dup(orig_dh); /* err check perfomed by dh_instance */
    obj = dh_instance(rb_obj_class(self), dh);
    if (obj == Qfalse) {
        DH_free(dh);
        ossl_raise(eDHError, NULL);
    }

    return obj;
}

Возвращает новый экземпляр DH, который содержит только публичную информацию, то есть простое число p и генератор g, но ещё не содержит пару открытого/закрытого ключа. Такую пару можно сгенерировать, используя #generate_key!. «Открытый ключ», необходимый для обмена ключами с #compute_key, считается сессионной информацией и может быть получен с помощью DH#pub_key после генерации пары ключей. Если текущий экземпляр уже содержит частную информацию (и, следовательно, пару открытого/закрытого ключа), эта информация больше не будет присутствовать в новом экземпляре, сгенерированном #public_key. Эта функция полезна для публикации параметров Диффи-Хеллмана без утечки каких-либо частных сессионных данных.

Пример

dh = OpenSSL::PKey::DH.new(2048) # has public and private key set
public_key = dh.public_key # contains only prime and generator
parameters = public_key.to_der # it's safe to publish this

set_key(pub_key, priv_key) → self

Устанавливает pub_key и priv_key для экземпляра DH. priv_key может быть nil.

set_pqg(p, q, g) → self

Устанавливает p, q, g для экземпляра DH.

to_der → aString Показать исходный код

static VALUE
ossl_dh_to_der(VALUE self)
{
    DH *dh;
    unsigned char *p;
    long len;
    VALUE str;

    GetDH(self, dh);
    if((len = i2d_DHparams(dh, NULL)) <= 0)
        ossl_raise(eDHError, NULL);
    str = rb_str_new(0, len);
    p = (unsigned char *)RSTRING_PTR(str);
    if(i2d_DHparams(dh, &p) < 0)
        ossl_raise(eDHError, NULL);
    ossl_str_adjust(str, p);

    return str;
}

Кодирует этот экземпляр DH в его кодировку DER. Обратите внимание, что любые существующие сессионные открытые/закрытые ключи не будут закодированы, будут закодированы только параметры Диффи-Хеллмана.

to_pem()

Псевдоним для: export

to_s()

Псевдоним для: export

to_text → aString Показать исходный код

static VALUE
ossl_dh_to_text(VALUE self)
{
    DH *dh;
    BIO *out;
    VALUE str;

    GetDH(self, dh);
    if (!(out = BIO_new(BIO_s_mem()))) {
        ossl_raise(eDHError, NULL);
    }
    if (!DHparams_print(out, dh)) {
        BIO_free(out);
        ossl_raise(eDHError, NULL);
    }
    str = ossl_membio2str(out);

    return str;
}

Выводит все параметры ключа в буфер НЕБЕЗОПАСНО: КОНФИДЕНЦИАЛЬНАЯ ИНФОРМАЦИЯ МОЖЕТ УТЕЧЬ!!! Не используйте :-)) (Это ваше решение)

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