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

Родитель:: OpenSSL::PKey::PKey
Включенные модули:: OpenSSL::Marshal

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

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

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

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

# you may send the parameters (der) and own public key (pub1) publicly
# to the participating party
dh1 = OpenSSL::PKey::DH.new(2048)
der = dh1.to_der
pub1 = dh1.pub_key

# the other party generates its per-session key pair
dhparams = OpenSSL::PKey::DH.new(der)
dh2 = OpenSSL::PKey.generate_key(dhparams)
pub2 = dh2.pub_key

symm_key1 = dh1.compute_key(pub2)
symm_key2 = dh2.compute_key(pub1)
puts symm_key1 == symm_key2 # => true

Методы класса (public)

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

# File ext/openssl/lib/openssl/pkey.rb, line 118
def generate(size, generator = 2, &blk)
  dhparams = OpenSSL::PKey.generate_parameters("DH", {
    "dh_paramgen_prime_len" => size,
    "dh_paramgen_generator" => generator,
  }, &blk)
  OpenSSL::PKey.generate_key(dhparams)
end

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

См. также OpenSSL::PKey.generate_parameters и OpenSSL::PKey.generate_key.

size: Требуемый размер ключа в битах.
generator: Генератор.

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

new(string) → dh

new(size [, generator]) → dh

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

    TypedData_Get_Struct(self, EVP_PKEY, &ossl_evp_pkey_type, pkey);
    if (pkey)
        rb_raise(rb_eTypeError, "pkey already initialized");

    /* The DH.new(size, generator) form is handled by lib/openssl/pkey.rb */
    if (rb_scan_args(argc, argv, "01", &arg) == 0) {
        dh = DH_new();
        if (!dh)
            ossl_raise(eDHError, "DH_new");
        goto legacy;
    }

    arg = ossl_to_der_if_possible(arg);
    in = ossl_obj2bio(&arg);

    /*
     * On OpenSSL <= 1.1.1 and current versions of LibreSSL, the generic
     * routine does not support DER-encoded parameters
     */
    dh = d2i_DHparams_bio(in, NULL);
    if (dh)
        goto legacy;
    OSSL_BIO_reset(in);

    pkey = ossl_pkey_read_generic(in, Qnil);
    BIO_free(in);
    if (!pkey)
        ossl_raise(eDHError, "could not parse pkey");

    type = EVP_PKEY_base_id(pkey);
    if (type != EVP_PKEY_DH) {
        EVP_PKEY_free(pkey);
        rb_raise(eDHError, "incorrect pkey type: %s", OBJ_nid2sn(type));
    }
    RTYPEDDATA_DATA(self) = pkey;
    return self;

  legacy:
    BIO_free(in);
    pkey = EVP_PKEY_new();
    if (!pkey || EVP_PKEY_assign_DH(pkey, dh) != 1) {
        EVP_PKEY_free(pkey);
        DH_free(dh);
        ossl_raise(eDHError, "EVP_PKEY_assign_DH");
    }
    RTYPEDDATA_DATA(self) = pkey;
    return self;
}

Создаёт новый экземпляр OpenSSL::PKey::DH.

Если вызывается без аргументов, создаётся пустой экземпляр без параметров или компонентов ключей. Используйте set_pqg, чтобы вручную задать параметры позже (и, необязательно, set_key, чтобы задать компоненты закрытого и открытого ключа).

Если передан объект String, пытается разобрать его как DER- или PEM- закодированные параметры. См. также OpenSSL::PKey.read, который может разбирать ключи любых типов.

Форма DH.new(size [, generator]) — псевдоним для DH.generate.

string: Объект String содержащий DER- или PEM- закодированный ключ.
size: См. DH.generate.
generator: См. DH.generate.

Примеры:

# Creating an instance from scratch
# Note that this is deprecated and will not work on OpenSSL 3.0 or later.
dh = OpenSSL::PKey::DH.new
dh.set_pqg(bn_p, nil, bn_g)

# Generating a parameters and a key pair
dh = OpenSSL::PKey::DH.new(2048) # An alias of OpenSSL::PKey::DH.generate(2048)

# Reading DH parameters
dh_params = OpenSSL::PKey::DH.new(File.read('parameters.pem')) # loads parameters only
dh = OpenSSL::PKey.generate_key(dh_params) # generates a key pair

Методы открытого экземпляра

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

# File ext/openssl/lib/openssl/pkey.rb, line 49
def compute_key(pub_bn)
  # FIXME: This is constructing an X.509 SubjectPublicKeyInfo and is very
  # inefficient
  obj = OpenSSL::ASN1.Sequence([
    OpenSSL::ASN1.Sequence([
      OpenSSL::ASN1.ObjectId("dhKeyAgreement"),
      OpenSSL::ASN1.Sequence([
        OpenSSL::ASN1.Integer(p),
        OpenSSL::ASN1.Integer(g),
      ]),
    ]),
    OpenSSL::ASN1.BitString(OpenSSL::ASN1.Integer(pub_bn).to_der),
  ])
  derive(OpenSSL::PKey.read(obj.to_der))
end

Возвращает String содержащий общий секрет, вычисленный из открытого значения другой стороны.

Этот метод предоставлен для обратной совместимости и вызывает derive внутри.

Параметры

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

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

static VALUE
ossl_dh_export(VALUE self)
{
    OSSL_3_const 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.

Обратите внимание, что любые существующие ключи (открытый/закрытый) на сессию не будут закодированы, будет закодированы только параметры Диффи-Хеллмана.

Закодированные параметрами PEM будут выглядеть так:

-----BEGIN DH PARAMETERS-----
[...]
-----END DH PARAMETERS-----

См. также public_to_pem (X.509 SubjectPublicKeyInfo) и private_to_pem (PKCS #8 PrivateKeyInfo или EncryptedPrivateKeyInfo) для сериализации с компонентами закрытого или открытого ключа.

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

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

# File ext/openssl/lib/openssl/pkey.rb, line 91
def generate_key!
  if OpenSSL::OPENSSL_VERSION_NUMBER >= 0x30000000
    raise DHError, "OpenSSL::PKey::DH is immutable on OpenSSL 3.0; " \
    "use OpenSSL::PKey.generate_key instead"
  end

  unless priv_key
    tmp = OpenSSL::PKey.generate_key(self)
    set_key(tmp.pub_key, tmp.priv_key)
  end
  self
end

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

Устарело начиная с версии 3.0. Этот метод несовместим с OpenSSL 3.0.0 или более поздними версиями.

См. также OpenSSL::PKey.generate_key.

Пример:

# DEPRECATED USAGE: This will not work on OpenSSL 3.0 or later
dh0 = OpenSSL::PKey::DH.new(2048)
dh = dh0.public_key # #public_key only copies the DH parameters (contrary to the name)
dh.generate_key!
puts dh.private? # => true
puts dh0.pub_key == dh.pub_key #=> false

# With OpenSSL::PKey.generate_key
dh0 = OpenSSL::PKey::DH.new(2048)
dh = OpenSSL::PKey.generate_key(dh0)
puts dh0.pub_key == dh.pub_key #=> false

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

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

    TypedData_Get_Struct(self, EVP_PKEY, &ossl_evp_pkey_type, pkey);
    if (pkey)
        rb_raise(rb_eTypeError, "pkey already initialized");
    GetDH(other, dh_other);

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

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

    pkey = EVP_PKEY_new();
    if (!pkey || EVP_PKEY_assign_DH(pkey, dh) != 1) {
        EVP_PKEY_free(pkey);
        DH_free(dh);
        ossl_raise(eDHError, "EVP_PKEY_assign_DH");
    }
    RTYPEDDATA_DATA(self) = pkey;
    return self;
}

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

static VALUE
ossl_dh_get_params(VALUE self)
{
    OSSL_3_const 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)
{
    int ret;
#ifdef HAVE_EVP_PKEY_CHECK
    EVP_PKEY *pkey;
    EVP_PKEY_CTX *pctx;

    GetPKey(self, pkey);
    pctx = EVP_PKEY_CTX_new(pkey, /* engine */NULL);
    if (!pctx)
        ossl_raise(eDHError, "EVP_PKEY_CTX_new");
    ret = EVP_PKEY_param_check(pctx);
    EVP_PKEY_CTX_free(pctx);
#else
    DH *dh;
    int codes;

    GetDH(self, dh);
    ret = DH_check(dh, &codes) == 1 && codes == 0;
#endif

    if (ret == 1)
        return Qtrue;
    else {
        /* DH_check_ex() will put error entry on failure */
        ossl_clear_error();
        return Qfalse;
    }
}

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

См. также страницу руководства EVP_PKEY_param_check(3).

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

static VALUE
ossl_dh_is_private(VALUE self)
{
    OSSL_3_const 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 *)dh)) ? Qtrue : Qfalse;
#else
    return bn ? Qtrue : Qfalse;
#endif
}

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

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

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

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

    return bn ? Qtrue : Qfalse;
}

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

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

# File ext/openssl/lib/openssl/pkey.rb, line 33
def public_key
  DH.new(to_der)
end

Возвращает новый экземпляр DH, который содержит только параметры DH.

Вопреки названию метода, возвращаемый объект DH содержит только параметры, а не открытый ключ.

Этот метод предоставлен для обратной совместимости. В большинстве случаев нет необходимости вызывать этот метод.

Для повторного создания пары ключей, сохраняя параметры, проверьте OpenSSL::PKey.generate_key.

Пример:

# OpenSSL::PKey::DH.generate by default generates a random key pair
dh1 = OpenSSL::PKey::DH.generate(2048)
p dh1.priv_key #=> #<OpenSSL::BN 1288347...>
dhcopy = dh1.public_key
p dhcopy.priv_key #=> nil

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)
{
    OSSL_3_const 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.

См. также public_to_der (X.509 SubjectPublicKeyInfo) и private_to_der (PKCS #8 PrivateKeyInfo или EncryptedPrivateKeyInfo) для сериализации с компонентами закрытого или открытого ключа.

to_pem → aString

Сериализует параметры DH в кодировку PEM.

Закодированные параметрами PEM будут выглядеть так:

-----BEGIN DH PARAMETERS-----
[...]
-----END DH PARAMETERS-----

Алиас для: export

to_s → aString

Сериализует параметры DH в кодировку PEM.

Закодированные параметрами PEM будут выглядеть так:

-----BEGIN DH PARAMETERS-----
[...]
-----END DH PARAMETERS-----

Алиас для: export

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