* ext/openssl/pkey_dh.c: clarify difference between DH#public_key and

DH#pub_key in documentation.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@32038 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ChangeLog

@@ -1,3 +1,8 @@
+Mon Jun 13 10:13:08 2011  Martin Bosslet  <Martin.Bosslet@googlemail.com>
+
+	* ext/openssl/pkey_dh.c: clarify difference between DH#public_key and
+	DH#pub_key in documentation.
+
 Mon Jun 13 05:50:43 2011  Martin Bosslet  <Martin.Bosslet@googlemail.com>
 
 	* NEWS: introduce PKey.read.

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
+ * * +size+ is an integer representing the desired key size. Keys smaller than 1024 bits should be considered insecure.
- * 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
+ * * +size+ is an integer representing the desired key size. Keys smaller than 1024 bits should be considered insecure.
- * 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!.
+ * a pair may be generated using DH#generate_key!. The "public key" needed
- * If the current instance already contains private information, this will no
+ * for a key exchange with DH#compute_key is considered as per-session
- * longer be present in the new instance. This feature is helpful for
+ * information and may be retrieved with DH#pub_key once a key pair has
- * publishing the public information without leaking any of the private
+ * been generated.
- * information.
+ * 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
+ *  dh = OpenSSL::PKey::DH.new(2048) # has public and private key set 
- *  pub_key = dh.public_key # contains only prime and generator
+ *  public_key = dh.public_key # contains only prime and generator
- *  pub_key_der = pub_key.to_der # it's safe to publish this
+ *  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);