diff options
Diffstat (limited to 'ext/openssl')
| -rw-r--r-- | ext/openssl/ossl_pkey_dh.c | 72 |
1 files changed, 54 insertions, 18 deletions
diff --git a/ext/openssl/ossl_pkey_dh.c b/ext/openssl/ossl_pkey_dh.c index 834261087a..464f41b156 100644 --- a/ext/openssl/ossl_pkey_dh.c +++ b/ext/openssl/ossl_pkey_dh.c @@ -107,8 +107,7 @@ dh_generate(int size, int gen) * components alike. * * === Parameters - * * +size+ is an integer representing the desired key size. Keys smaller than - * 1024 bits should be considered insecure. + * * +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. * */ @@ -137,11 +136,13 @@ ossl_dh_s_generate(int argc, VALUE *argv, VALUE klass) * DH.new([size [, generator] | string]) -> dh * * Either generates a DH instance from scratch or by reading already existing - * DH parameters from +string+. + * DH parameters from +string+. Note that when reading a DH instance from + * data that was encoded from a DH#public_key DH instance the result + * will *not* contain a public/private key pair yet. This needs to be + * generated using DH#generate_key! first. * * === Parameters - * * +size+ is an integer representing the desired key size. Keys smaller than - * 1024 bits should be considered insecure. + * * +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. * @@ -149,7 +150,11 @@ ossl_dh_s_generate(int argc, VALUE *argv, VALUE klass) * DH.new # -> dh * DH.new(1024) # -> dh * DH.new(1024, 5) # -> dh + * #Reading a "private" DH key * DH.new(File.read('key.pem')) # -> dh + * #Reading public 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 */ static VALUE ossl_dh_initialize(int argc, VALUE *argv, VALUE self) @@ -199,7 +204,7 @@ ossl_dh_initialize(int argc, VALUE *argv, VALUE self) * dh.public? -> true | false * * Indicates whether this DH instance has a public key associated with it or - * not. The public key may be retrieved with DH#public_key. + * not. The public key may be retrieved with DH#pub_key. */ static VALUE ossl_dh_is_public(VALUE self) @@ -216,7 +221,7 @@ ossl_dh_is_public(VALUE self) * dh.private? -> true | false * * Indicates whether this DH instance has a private key associated with it or - * not. The private key may be retrieved with DH#private_key. + * not. The private key may be retrieved with DH#priv_key. */ static VALUE ossl_dh_is_private(VALUE self) @@ -340,16 +345,20 @@ ossl_dh_to_text(VALUE self) * * 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 DH#generate_key!. - * If the current instance already contains private information, this will no - * longer be present in the new instance. This feature is helpful for - * publishing the public information without leaking any of the private - * information. + * a pair may be generated using DH#generate_key!. The "public key" needed + * for a key exchange with DH#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 DH#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 information - * pub_key = dh.public_key # contains only prime and generator - * pub_key_der = pub_key.to_der # it's safe to publish this + * 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 */ static VALUE ossl_dh_to_public_key(VALUE self) @@ -398,7 +407,11 @@ ossl_dh_check_params(VALUE self) * call-seq: * dh.generate_key! -> self * - * Generates a private and public key unless one already exists. + * 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 DH#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) @@ -424,11 +437,12 @@ ossl_dh_generate_key(VALUE self) * call-seq: * dh.compute_key(pub_bn) -> aString * - * Returns aString containing a shared secret computed from the other parties public value. + * 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. + * * +pub_bn+ is a OpenSSL::BN, *not* the DH instance returned by + * DH#public_key as that contains the DH parameters only. */ static VALUE ossl_dh_compute_key(VALUE self, VALUE pub) @@ -543,6 +557,27 @@ Init_ossl_dh() * 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) + * params = 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 */ cDH = rb_define_class_under(mPKey, "DH", cPKey); rb_define_singleton_method(cDH, "generate", ossl_dh_s_generate, -1); @@ -558,6 +593,7 @@ Init_ossl_dh() rb_define_method(cDH, "params_ok?", ossl_dh_check_params, 0); rb_define_method(cDH, "generate_key!", ossl_dh_generate_key, 0); rb_define_method(cDH, "compute_key", ossl_dh_compute_key, 1); + DEF_OSSL_PKEY_BN(cDH, dh, p); DEF_OSSL_PKEY_BN(cDH, dh, g); DEF_OSSL_PKEY_BN(cDH, dh, pub_key); |