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 #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
Constant Summary
-
DEFAULT_1024 =
# File 'ext/openssl/lib/openssl/pkey.rb', line 14new <<-_end_of_pem_ -----BEGIN DH PARAMETERS----- MIGHAoGBAJ0lOVy0VIr/JebWn0zDwY2h+rqITFOpdNr6ugsgvkDXuucdcChhYExJ AV/ZD2AWPbrTqV76mGRgJg4EddgT1zG0jq3rnFdMj2XzkBYx3BVvfR0Arnby0RHR T4h7KZ/2zmjvV+eF8kBUHBJAojUlzxKj4QeO2x20FP9X5xmNUXeDAgEC -----END DH PARAMETERS----- _end_of_pem_
-
DEFAULT_512 =
# File 'ext/openssl/lib/openssl/pkey.rb', line 7new <<-_end_of_pem_ -----BEGIN DH PARAMETERS----- MEYCQQD0zXHljRg/mJ9PYLACLv58Cd8VxBxxY7oEuCeURMiTqEhMym16rhhKgZG2 zk2O9uUIBIxSj+NKMURHGaFKyIvLAgEC -----END DH PARAMETERS----- _end_of_pem_
Class Method Summary
-
.generate(size [, generator]) ⇒ DH
Creates a new
DH
instance from scratch by generating the private and public components alike. -
.new([size [, generator] | string]) ⇒ DH
constructor
Either generates a
DH
instance from scratch or by reading already existingDH
parameters fromstring
.
PKey - Inherited
.new | Because PKey is an abstract class, actually calling this method explicitly will raise a |
Instance Attribute Summary
-
#params_ok? ⇒ Boolean
readonly
Validates the Diffie-Hellman parameters associated with this instance.
-
#private? ⇒ Boolean
readonly
Indicates whether this
DH
instance has a private key associated with it or not. -
#public? ⇒ Boolean
readonly
Indicates whether this
DH
instance has a public key associated with it or not.
Instance Method Summary
-
#compute_key(pub_bn) ⇒ String
Returns a String containing a shared secret computed from the other party's public value.
-
#export ⇒ String
Alias for #to_s.
-
#generate_key! ⇒ self
Generates a private and public key unless a private key already exists.
-
#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 primep
and the generatorg
, but no public/private key yet. -
#to_der ⇒ String
Encodes this
DH
to its DER encoding. -
#to_pem ⇒ String
Alias for #to_s.
-
#to_s ⇒ String
(also: #export, #to_pem)
Encodes this
DH
to its PEM encoding. -
#to_text ⇒ String
Prints all parameters of key to buffer INSECURE: PRIVATE INFORMATIONS CAN LEAK OUT!!! Don't use :-)) (I's up to you).
PKey - Inherited
#sign | To sign the |
#verify | To verify the |
Constructor Details
.new([size [, generator] | string]) ⇒ 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 theDH
instance returned by
#public_key as that contains the DH
parameters only.
#export ⇒ String
#to_pem ⇒ String
#to_s ⇒ String
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
#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
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
String
#to_pem ⇒ String
#to_s ⇒ String
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)