summaryrefslogtreecommitdiff
path: root/ext/openssl/ossl_pkey_dh.c
diff options
context:
space:
mode:
authoremboss <emboss@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2011-06-13 01:15:20 +0000
committeremboss <emboss@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2011-06-13 01:15:20 +0000
commit149f35fc6ee42eb006300378daf002d998a9a07f (patch)
tree8add90f06d47812edc2bc85f4a82277b8af3d8e9 /ext/openssl/ossl_pkey_dh.c
parentbec36af2d12c0c1187ea4528c3b2fc03ec97395e (diff)
* 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
Diffstat (limited to 'ext/openssl/ossl_pkey_dh.c')
-rw-r--r--ext/openssl/ossl_pkey_dh.c72
1 files changed, 54 insertions, 18 deletions
diff --git a/ext/openssl/ossl_pkey_dh.c b/ext/openssl/ossl_pkey_dh.c
index 8342610..464f41b 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);