123456789_123456789_123456789_123456789_123456789_

Class: OpenSSL::PKey::DH

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, PKey
Instance Chain:
self, PKey
Inherits: OpenSSL::PKey::PKey
Defined in: ext/openssl/ossl_pkey_dh.c,
ext/openssl/lib/openssl/pkey.rb

Overview

An implementation of the Diffie-Hellman key exchange protocol based on discrete logarithms in finite fields, the same basis that DSA is built on.

Accessor methods for the Diffie-Hellman parameters

DH#p

The prime (an OpenSSL::BN) of the Diffie-Hellman parameters.

DH#g

The generator (an OpenSSL::BN) g of the Diffie-Hellman parameters.

DH#pub_key

The per-session public key (an OpenSSL::BN) matching the private key. This needs to be passed to DH#compute_key.

DH#priv_key

The per-session private key, an OpenSSL::BN.

Example of a key exchange

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

Class Method Summary

  • .generate(size [, generator]) ⇒ DH

    Creates a new DH instance from scratch by generating the private and public components alike.

  • .new ⇒ DH constructor

    Either generates a DH instance from scratch or by reading already existing DH parameters from string.

PKey - Inherited

.new

Because PKey is an abstract class, actually calling this method explicitly will raise a NotImplementedError.

Instance Attribute Summary

Instance Method Summary

PKey - Inherited

#sign

To sign the String data, digest, an instance of ::OpenSSL::Digest, must be provided.
#verify

To verify the String signature, digest, an instance of ::OpenSSL::Digest, must be provided to re-compute the message digest of the original data, also a String.

Constructor Details

.new ⇒ DH .new(string) ⇒ DH .new(size [, generator]) ⇒ DH

Either generates a DH instance from scratch or by reading already existing DH parameters from string. Note that when reading a DH instance from data that was encoded from a DH instance by using #to_pem or #to_der the result will not contain a public/private key pair yet. This needs to be generated using #generate_key! first.

Parameters

  • size is an integer representing the desired key size. Keys smaller than 1024 bits should be considered insecure.

  • generator is a small number > 1, typically 2 or 5.

  • string contains the DER or PEM encoded key.

Examples

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

Class Method Details

.generate(size [, generator]) ⇒ DH

Creates a new DH instance from scratch by generating the private and public components alike.

Parameters

  • size is an integer representing the desired key size. Keys smaller than 1024 bits should be considered insecure.

  • generator is a small number > 1, typically 2 or 5.

Instance Attribute Details

#params_ok? ⇒ Boolean (readonly)

Validates the Diffie-Hellman parameters associated with this instance. It checks whether a safe prime and a suitable generator are used. If this is not the case, false is returned.

#private? ⇒ Boolean (readonly)

Indicates whether this DH instance has a private key associated with it or not. The private key may be retrieved with DH#priv_key.

#public? ⇒ Boolean (readonly)

Indicates whether this DH instance has a public key associated with it or not. The public key may be retrieved with DH#pub_key.

Instance Method Details

#compute_key(pub_bn) ⇒ String

Returns a String containing a shared secret computed from the other party's public value. See DH_compute_key() for further information.

Parameters

  • pub_bn is a ::OpenSSL::BN, not the DH instance returned by DH#public_key as that contains the DH parameters only.

#export ⇒ String #to_pem ⇒ String #to_s ⇒ String

Alias for #to_s.

#generate_key! ⇒ self

Generates a private and public key unless a private key already exists. If this DH instance was generated from public DH parameters (e.g. by encoding the result of #public_key), then this method needs to be called first in order to generate the per-session keys before performing the actual key exchange.

Example

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

#params ⇒ Hash

Stores all parameters of key to the hash INSECURE: PRIVATE INFORMATIONS CAN LEAK OUT!!! Don't use :-)) (I's up to you)

#public_key ⇒ DH

Returns a new DH instance that carries just the public information, i.e. the prime p and the generator g, but no public/private key yet. Such a pair may be generated using #generate_key!. The “public key” needed for a key exchange with #compute_key is considered as per-session information and may be retrieved with DH#pub_key once a key pair has been generated. If the current instance already contains private information (and thus a valid public/private key pair), this information will no longer be present in the new instance generated by #public_key. This feature is helpful for publishing the Diffie-Hellman parameters without leaking any of the private per-session information.

Example

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

Sets pub_key and priv_key for the DH instance. priv_key may be nil.

#set_pqg(p, q, g) ⇒ self

Sets p, q, g for the DH instance.

#to_der ⇒ String

Encodes this DH to its DER encoding. Note that any existing per-session public/private keys will not get encoded, just the Diffie-Hellman parameters will be encoded.

#export ⇒ String #to_pem ⇒ String #to_s ⇒ String

Alias for #to_s.

#export ⇒ String #to_pem ⇒ String #to_s ⇒ String
Also known as: #export, #to_pem

Encodes this DH to its PEM encoding. Note that any existing per-session public/private keys will not get encoded, just the Diffie-Hellman parameters will be encoded.

#to_text ⇒ String

Prints all parameters of key to buffer INSECURE: PRIVATE INFORMATIONS CAN LEAK OUT!!! Don't use :-)) (I's up to you)