class OpenSSL::PKey::DH

Eine Implementierung des Diffie-Hellman-Schlüsselaustauschprotokolls basierend auf diskreten Logarithmen in endlichen Körpern, derselben Grundlage, auf der DSA aufbaut.

Accessor-Methoden für die Diffie-Hellman-Parameter

DH#p: Die Primzahl (eine OpenSSL::BN) der Diffie-Hellman-Parameter.
DH#g: Der Generator (eine OpenSSL::BN) g der Diffie-Hellman-Parameter.
DH#pub_key: Der sitzungsspezifische öffentliche Schlüssel (eine OpenSSL::BN), der zum privaten Schlüssel passt. Dieser muss an DH#compute_key übergeben werden.
DH#priv_key: Der sitzungsspezifische private Schlüssel, eine OpenSSL::BN.

Beispiel für einen Schlüsselaustausch

# 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

Öffentliche Klassenmethoden

generate(size, generator = 2) → dh

Source

# File ext/openssl/lib/openssl/pkey.rb, line 133
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

Erstellt eine neue DH-Instanz von Grund auf neu, indem zufällige Parameter und ein Schlüsselpaar generiert werden.

Siehe auch OpenSSL::PKey.generate_parameters und OpenSSL::PKey.generate_key.

size: Die gewünschte Schlüsselgröße in Bits.
generator: Der Generator.

new → dh

new(string) → dh

new(size [, generator]) → dh

Source

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) {
#ifdef OSSL_HAVE_IMMUTABLE_PKEY
        rb_raise(rb_eArgError, "OpenSSL::PKey::DH.new cannot be called " \
                 "without arguments; pkeys are immutable with OpenSSL 3.0");
#else
        dh = DH_new();
        if (!dh)
            ossl_raise(ePKeyError, "DH_new");
        goto legacy;
#endif
    }

    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(ePKeyError, "could not parse pkey");

    type = EVP_PKEY_base_id(pkey);
    if (type != EVP_PKEY_DH) {
        EVP_PKEY_free(pkey);
        rb_raise(ePKeyError, "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(ePKeyError, "EVP_PKEY_assign_DH");
    }
    RTYPEDDATA_DATA(self) = pkey;
    return self;
}

Erstellt eine neue Instanz von OpenSSL::PKey::DH.

Wenn ohne Argumente aufgerufen, wird eine leere Instanz ohne Parameter- oder Schlüsselkomponenten erstellt. Verwenden Sie set_pqg, um die Parameter manuell festzulegen (und optional set_key, um private und öffentliche Schlüsselkomponenten festzulegen). Diese Form ist nicht kompatibel mit OpenSSL 3.0 oder höher.

Wenn ein String angegeben wird, wird versucht, ihn als DER- oder PEM-kodierte Parameter zu parsen. Siehe auch OpenSSL::PKey.read, der Schlüssel jeder Art parsen kann.

Die Form DH.new(size [, generator]) ist ein Alias für DH.generate.

Zeichenkette: Ein String, der den DER- oder PEM-kodierten Schlüssel enthält.
size: Siehe DH.generate.
generator: Siehe DH.generate.

Beispiele

# Creating an instance from scratch
# Note that this is deprecated and will result in ArgumentError when
# using 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 from a PEM-encoded string
dh_params = OpenSSL::PKey::DH.new(File.read('parameters.pem')) # loads parameters only
dh = OpenSSL::PKey.generate_key(dh_params) # generates a key pair

Öffentliche Instanzmethoden

compute_key(pub_bn) → string

Source

# File ext/openssl/lib/openssl/pkey.rb, line 64
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

Gibt einen String zurück, der ein von der öffentlichen Kennung der anderen Partei berechnetes gemeinsames Geheimnis enthält.

Diese Methode dient der Rückwärtskompatibilität und ruft intern derive auf.

Parameter

pub_bn ist eine OpenSSL::BN, **nicht** die von DH#public_key zurückgegebene DH-Instanz, da diese nur die DH-Parameter enthält.

export → aString

Source

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(ePKeyError, NULL);
    }
    if (!PEM_write_bio_DHparams(out, dh)) {
        BIO_free(out);
        ossl_raise(ePKeyError, NULL);
    }
    str = ossl_membio2str(out);

    return str;
}

Serialisiert die DH-Parameter in eine PEM-Kodierung.

Beachten Sie, dass sitzungsspezifische öffentliche/private Schlüssel **nicht** kodiert werden, nur die Diffie-Hellman-Parameter werden kodiert.

PEM-kodierte Parameter sehen so aus

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

Siehe auch public_to_pem (X.509 SubjectPublicKeyInfo) und private_to_pem (PKCS #8 PrivateKeyInfo oder EncryptedPrivateKeyInfo) für die Serialisierung mit den privaten oder öffentlichen Schlüsselkomponenten.

Auch alias genannt: to_pem, to_s

generate_key! → self

Source

# File ext/openssl/lib/openssl/pkey.rb, line 106
def generate_key!
  if OpenSSL::OPENSSL_VERSION_NUMBER >= 0x30000000
    raise PKeyError, "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

Generiert einen privaten und einen öffentlichen Schlüssel, es sei denn, ein privater Schlüssel existiert bereits. Wenn diese DH-Instanz aus öffentlichen DH-Parametern generiert wurde (z. B. durch Kodierung des Ergebnisses von DH#public_key), muss diese Methode zuerst aufgerufen werden, um die sitzungsspezifischen Schlüssel zu generieren, bevor der eigentliche Schlüsselaustausch durchgeführt wird.

Veraltet in Version 3.0. Diese Methode ist mit OpenSSL 3.0.0 oder neuer nicht kompatibel.

Siehe auch OpenSSL::PKey.generate_key.

Beispiel

# 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

params → hash

Source

# File ext/openssl/lib/openssl/pkey.rb, line 46
def params
  %w{p q g pub_key priv_key}.map { |name|
    [name, send(name)]
  }.to_h
end

Speichert alle Parameter des Schlüssels in einem Hash.

Der Hash hat die Schlüssel ‘p’, ‘q’, ‘g’, ‘pub_key’ und ‘priv_key’.

params_ok? → true | false

Source

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(ePKeyError, "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;
    }
}

Validiert die mit dieser Instanz verbundenen Diffie-Hellman-Parameter. Sie prüft, ob eine sichere Primzahl und ein geeigneter Generator verwendet werden. Wenn dies nicht der Fall ist, wird false zurückgegeben.

Siehe auch die Manpage EVP_PKEY_param_check(3).

private? → true | false

Source

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
}

Gibt an, ob diese DH-Instanz einen zugeordneten privaten Schlüssel hat oder nicht. Der private Schlüssel kann mit DH#priv_key abgerufen werden.

public? → true | false

Source

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

Gibt an, ob diese DH-Instanz einen zugeordneten öffentlichen Schlüssel hat oder nicht. Der öffentliche Schlüssel kann mit DH#pub_key abgerufen werden.

public_key → dhnew

Source

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

Gibt eine neue DH-Instanz zurück, die nur die DH-Parameter enthält.

Entgegen dem Methodennamen enthält das zurückgegebene DH-Objekt nur Parameter und nicht den öffentlichen Schlüssel.

Diese Methode wird aus Gründen der Abwärtskompatibilität bereitgestellt. In den meisten Fällen ist es nicht erforderlich, diese Methode aufzurufen.

Um das Schlüsselpaar bei Beibehaltung der Parameter neu zu generieren, siehe OpenSSL::PKey.generate_key.

Beispiel

# 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

Setzt pub_key und priv_key für die DH-Instanz. priv_key kann nil sein.

set_pqg(p, q, g) → self

Setzt p, q, g für die DH-Instanz.

to_der → aString

Source

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(ePKeyError, NULL);
    str = rb_str_new(0, len);
    p = (unsigned char *)RSTRING_PTR(str);
    if(i2d_DHparams(dh, &p) < 0)
        ossl_raise(ePKeyError, NULL);
    ossl_str_adjust(str, p);

    return str;
}

Serialisiert die DH-Parameter in eine DER-Kodierung

Beachten Sie, dass sitzungsspezifische öffentliche/private Schlüssel **nicht** kodiert werden, nur die Diffie-Hellman-Parameter werden kodiert.

Siehe auch public_to_der (X.509 SubjectPublicKeyInfo) und private_to_der (PKCS #8 PrivateKeyInfo oder EncryptedPrivateKeyInfo) für die Serialisierung mit den privaten oder öffentlichen Schlüsselkomponenten.

to_pem → aString

Serialisiert die DH-Parameter in eine PEM-Kodierung.

Beachten Sie, dass sitzungsspezifische öffentliche/private Schlüssel **nicht** kodiert werden, nur die Diffie-Hellman-Parameter werden kodiert.

PEM-kodierte Parameter sehen so aus

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

Alias für: export

to_s → aString

Serialisiert die DH-Parameter in eine PEM-Kodierung.

Beachten Sie, dass sitzungsspezifische öffentliche/private Schlüssel **nicht** kodiert werden, nur die Diffie-Hellman-Parameter werden kodiert.

PEM-kodierte Parameter sehen so aus

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

Alias für: export