* ext/openssl/ossl_{bn,x509{attr,cert,name,store}}.c:

  Add documentation.



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

6 files changed, 216 insertions, 8 deletions

diff --git a/ChangeLog b/ChangeLog
index 6d9ae10f8d..cd56ba66c4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+Fri Apr  6 04:00:24 2007  Technorama Ltd.  <oss-ruby@technorama.net>
+
+	* ext/openssl/ossl_{bn,x509{attr,cert,name,store}}.c:
+	  Add documentation.
+
+
 Thu Apr  5 17:59:19 2007  Nobuyoshi Nakada  <nobu@ruby-lang.org>
 
 	* compile.c (defined_expr): support for assignment.
diff --git a/ext/openssl/ossl_bn.c b/ext/openssl/ossl_bn.c
index 13aed7f4be..60d9e552a4 100644
--- a/ext/openssl/ossl_bn.c
+++ b/ext/openssl/ossl_bn.c
@@ -104,6 +104,7 @@ ossl_bn_alloc(VALUE klass)
  * call-seq:
  *    BN.new => aBN
  *    BN.new(bn) => aBN
+ *    BN.new(string) => aBN
  *    BN.new(string, 0 | 2 | 10 | 16) => aBN
  */
 static VALUE
@@ -155,6 +156,19 @@ ossl_bn_initialize(int argc, VALUE *argv, VALUE self)
     return self;
 }
 
+/*
+ * call-seq:
+ *    bn.to_s => string
+ *    bn.to_s(base) => string
+ *
+ * === Parameters
+ * * +base+ - integer
+ * * * Valid values:
+ * * * * 0 - MPI
+ * * * * 2 - binary
+ * * * * 10 - the default
+ * * * * 16 - hex
+ */
 static VALUE
 ossl_bn_to_s(int argc, VALUE *argv, VALUE self)
 {
@@ -340,6 +354,10 @@ BIGNUM_2c(gcd);
 BIGNUM_2c(mod_sqr);
 BIGNUM_2c(mod_inverse);
 
+/*
+ * call-seq:
+ *    bn1 / bn2 => [result, remainder]
+ */
 static VALUE
 ossl_bn_div(VALUE self, VALUE other)
 {
@@ -414,6 +432,10 @@ BIGNUM_BIT(set_bit);
 BIGNUM_BIT(clear_bit);
 BIGNUM_BIT(mask_bits);
 
+/*
+ * call-seq:
+ *    bn.bit_set?(bit) => true | false
+ */
 static VALUE
 ossl_bn_is_bit_set(VALUE self, VALUE bit)
 {
@@ -533,6 +555,16 @@ BIGNUM_RAND(pseudo_rand);
 BIGNUM_RAND_RANGE(rand);
 BIGNUM_RAND_RANGE(pseudo_rand);
 
+/*
+ * call-seq:
+ *    BN.generate_prime(bits, [, safe [, add [, rem]]]) => bn
+ *
+ * === Parameters
+ * * +bits+ - integer
+ * * +safe+ - boolean
+ * * +add+ - BN
+ * * +rem+ - BN
+ */
 static VALUE
 ossl_bn_s_generate_prime(int argc, VALUE *argv, VALUE klass)
 {
@@ -548,12 +580,8 @@ ossl_bn_s_generate_prime(int argc, VALUE *argv, VALUE klass)
 	safe = 0;
     }
     if (!NIL_P(vadd)) {
-	if (NIL_P(vrem)) {
-	    ossl_raise(rb_eArgError,
-		       "if ADD is specified, REM must be also given");
-	}
 	add = GetBNPtr(vadd);
-	rem = GetBNPtr(vrem);
+	rem = NIL_P(vrem) ? NULL : GetBNPtr(vrem);
     }
     if (!(result = BN_new())) {
 	ossl_raise(eBNError, NULL);
@@ -564,7 +592,7 @@ ossl_bn_s_generate_prime(int argc, VALUE *argv, VALUE klass)
     }
     WrapBN(klass, obj, result);
     
-	return obj;
+    return obj;
 }
 
 #define BIGNUM_NUM(func)			\
@@ -626,6 +654,14 @@ ossl_bn_eql(VALUE self, VALUE other)
     return Qfalse;
 }
 
+/*
+ * call-seq:
+ *    bn.prime? => true | false
+ *    bn.prime?(checks) => true | false
+ *
+ * === Parameters
+ * * +checks+ - integer
+ */
 static VALUE
 ossl_bn_is_prime(int argc, VALUE *argv, VALUE self)
 {
@@ -649,6 +685,16 @@ ossl_bn_is_prime(int argc, VALUE *argv, VALUE self)
     return Qnil;
 }
 
+/*
+ * call-seq:
+ *    bn.prime_fasttest? => true | false
+ *    bn.prime_fasttest?(checks) => true | false
+ *    bn.prime_fasttest?(checks, trial_div) => true | false
+ *
+ * === Parameters
+ * * +checks+ - integer
+ * * +trial_div+ - boolean
+ */
 static VALUE
 ossl_bn_is_prime_fasttest(int argc, VALUE *argv, VALUE self)
 {
diff --git a/ext/openssl/ossl_x509attr.c b/ext/openssl/ossl_x509attr.c
index 267bd81855..ca1c59aba9 100644
--- a/ext/openssl/ossl_x509attr.c
+++ b/ext/openssl/ossl_x509attr.c
@@ -84,6 +84,10 @@ ossl_x509attr_alloc(VALUE klass)
     return obj;
 }
 
+/*
+ * call-seq:
+ *    Attribute.new(oid [, value]) => attr
+ */
 static VALUE
 ossl_x509attr_initialize(int argc, VALUE *argv, VALUE self)
 {
@@ -108,6 +112,10 @@ ossl_x509attr_initialize(int argc, VALUE *argv, VALUE self)
     return self;
 }
 
+/*
+ * call-seq:
+ *    attr.oid = string => string
+ */
 static VALUE
 ossl_x509attr_set_oid(VALUE self, VALUE oid)
 {
@@ -125,6 +133,10 @@ ossl_x509attr_set_oid(VALUE self, VALUE oid)
     return oid;
 }
 
+/*
+ * call-seq:
+ *    attr.oid => string
+ */
 static VALUE
 ossl_x509attr_get_oid(VALUE self)
 {
@@ -156,6 +168,10 @@ ossl_x509attr_get_oid(VALUE self)
 #  define OSSL_X509ATTR_SET_SINGLE(attr) ((attr)->set = 0)
 #endif
 
+/*
+ * call-seq:
+ *    attr.value = asn1 => asn1
+ */
 static VALUE
 ossl_x509attr_set_value(VALUE self, VALUE value)
 {
@@ -179,6 +195,10 @@ ossl_x509attr_set_value(VALUE self, VALUE value)
     return value;
 }
 
+/*
+ * call-seq:
+ *    attr.value => asn1
+ */
 static VALUE
 ossl_x509attr_get_value(VALUE self)
 {
@@ -210,6 +230,10 @@ ossl_x509attr_get_value(VALUE self)
     return asn1;
 }
 
+/*
+ * call-seq:
+ *    attr.to_der => string
+ */
 static VALUE
 ossl_x509attr_to_der(VALUE self)
 {
diff --git a/ext/openssl/ossl_x509cert.c b/ext/openssl/ossl_x509cert.c
index 0276764f83..b97f27ffa9 100644
--- a/ext/openssl/ossl_x509cert.c
+++ b/ext/openssl/ossl_x509cert.c
@@ -125,6 +125,11 @@ ossl_x509_alloc(VALUE klass)
     return obj;
 }
 
+/*
+ * call-seq:
+ *    Certificate.new => cert
+ *    Certificate.new(string) => cert
+ */
 static VALUE 
 ossl_x509_initialize(int argc, VALUE *argv, VALUE self)
 {
@@ -169,6 +174,10 @@ ossl_x509_copy(VALUE self, VALUE other)
     return self;
 }
 
+/*
+ * call-seq:
+ *    cert.to_der => string
+ */
 static VALUE 
 ossl_x509_to_der(VALUE self)
 {
@@ -189,6 +198,10 @@ ossl_x509_to_der(VALUE self)
     return str;
 }
 
+/*
+ * call-seq:
+ *    cert.to_pem => string
+ */
 static VALUE 
 ossl_x509_to_pem(VALUE self)
 {
@@ -209,6 +222,10 @@ ossl_x509_to_pem(VALUE self)
     return str;
 }
 
+/*
+ * call-seq:
+ *    cert.to_text => string
+ */
 static VALUE
 ossl_x509_to_text(VALUE self)
 {
@@ -252,6 +269,10 @@ ossl_x509_to_req(VALUE self)
 }
 #endif
 
+/*
+ * call-seq:
+ *    cert.version => integer
+ */
 static VALUE 
 ossl_x509_get_version(VALUE self)
 {
@@ -262,6 +283,10 @@ ossl_x509_get_version(VALUE self)
     return LONG2NUM(X509_get_version(x509));
 }
 
+/*
+ * call-seq:
+ *    cert.version = integer => integer
+ */
 static VALUE 
 ossl_x509_set_version(VALUE self, VALUE version)
 {
@@ -279,6 +304,10 @@ ossl_x509_set_version(VALUE self, VALUE version)
     return version;
 }
 
+/*
+ * call-seq:
+ *    cert.serial => integer
+ */
 static VALUE 
 ossl_x509_get_serial(VALUE self)
 {
@@ -289,6 +318,10 @@ ossl_x509_get_serial(VALUE self)
     return asn1integer_to_num(X509_get_serialNumber(x509));
 }
 
+/*
+ * call-seq:
+ *    cert.serial = integer => integer
+ */
 static VALUE 
 ossl_x509_set_serial(VALUE self, VALUE num)
 {
@@ -302,6 +335,10 @@ ossl_x509_set_serial(VALUE self, VALUE num)
     return num;
 }
 
+/*
+ * call-seq:
+ *    cert.signature_algorithm => string
+ */
 static VALUE 
 ossl_x509_get_signature_algorithm(VALUE self)
 {
@@ -322,6 +359,10 @@ ossl_x509_get_signature_algorithm(VALUE self)
     return str;
 }
 
+/*
+ * call-seq:
+ *    cert.subject => name
+ */
 static VALUE 
 ossl_x509_get_subject(VALUE self)
 {
@@ -336,6 +377,10 @@ ossl_x509_get_subject(VALUE self)
     return ossl_x509name_new(name);
 }
 
+/*
+ * call-seq:
+ *    cert.subject = name => name
+ */
 static VALUE 
 ossl_x509_set_subject(VALUE self, VALUE subject)
 {
@@ -349,6 +394,10 @@ ossl_x509_set_subject(VALUE self, VALUE subject)
     return subject;
 }
 
+/*
+ * call-seq:
+ *    cert.issuer => name
+ */
 static VALUE 
 ossl_x509_get_issuer(VALUE self)
 {
@@ -363,6 +412,10 @@ ossl_x509_get_issuer(VALUE self)
     return ossl_x509name_new(name);
 }
 
+/*
+ * call-seq:
+ *    cert.issuer = name => name
+ */
 static VALUE 
 ossl_x509_set_issuer(VALUE self, VALUE issuer)
 {
@@ -376,6 +429,10 @@ ossl_x509_set_issuer(VALUE self, VALUE issuer)
     return issuer;
 }
 
+/*
+ * call-seq:
+ *    cert.not_before => time
+ */
 static VALUE 
 ossl_x509_get_not_before(VALUE self)
 {
@@ -390,6 +447,10 @@ ossl_x509_get_not_before(VALUE self)
     return asn1time_to_time(asn1time);
 }
 
+/*
+ * call-seq:
+ *    cert.not_before = time => time
+ */
 static VALUE 
 ossl_x509_set_not_before(VALUE self, VALUE time)
 {
@@ -405,6 +466,10 @@ ossl_x509_set_not_before(VALUE self, VALUE time)
     return time;
 }
 
+/*
+ * call-seq:
+ *    cert.not_after => time
+ */
 static VALUE 
 ossl_x509_get_not_after(VALUE self)
 {
@@ -419,6 +484,10 @@ ossl_x509_get_not_after(VALUE self)
     return asn1time_to_time(asn1time);
 }
 
+/*
+ * call-seq:
+ *    cert.not_before = time => time
+ */
 static VALUE 
 ossl_x509_set_not_after(VALUE self, VALUE time)
 {
@@ -434,6 +503,10 @@ ossl_x509_set_not_after(VALUE self, VALUE time)
     return time;
 }
 
+/*
+ * call-seq:
+ *    cert.public_key => key
+ */
 static VALUE 
 ossl_x509_get_public_key(VALUE self)
 {
@@ -448,6 +521,10 @@ ossl_x509_get_public_key(VALUE self)
     return ossl_pkey_new(pkey); /* NO DUP - OK */
 }
 
+/*
+ * call-seq:
+ *    cert.public_key = key => key
+ */
 static VALUE 
 ossl_x509_set_public_key(VALUE self, VALUE key)
 {
@@ -461,6 +538,10 @@ ossl_x509_set_public_key(VALUE self, VALUE key)
     return key;
 }
 
+/*
+ * call-seq:
+ *    cert.sign(key, digest) => self
+ */
 static VALUE 
 ossl_x509_sign(VALUE self, VALUE key, VALUE digest)
 {
@@ -479,6 +560,9 @@ ossl_x509_sign(VALUE self, VALUE key, VALUE digest)
 }
 
 /*
+ * call-seq:
+ *    cert.verify(key) => true | false
+ *
  * Checks that cert signature is made with PRIVversion of this PUBLIC 'key'
  */
 static VALUE 
@@ -501,6 +585,9 @@ ossl_x509_verify(VALUE self, VALUE key)
 }
 
 /*
+ * call-seq:
+ *    cert.check_private_key(key)
+ *
  * Checks if 'key' is PRIV key for this cert
  */
 static VALUE 
@@ -521,7 +608,8 @@ ossl_x509_check_private_key(VALUE self, VALUE key)
 }
 
 /*
- * Gets X509v3 extensions as array of X509Ext objects
+ * call-seq:
+ *    cert.extensions => [extension...]
  */
 static VALUE 
 ossl_x509_get_extensions(VALUE self)
@@ -546,7 +634,8 @@ ossl_x509_get_extensions(VALUE self)
 }
 
 /*
- * Sets X509_EXTENSIONs
+ * call-seq:
+ *    cert.extensions = [ext...] => [ext...]
  */
 static VALUE 
 ossl_x509_set_extensions(VALUE self, VALUE ary)
@@ -576,6 +665,10 @@ ossl_x509_set_extensions(VALUE self, VALUE ary)
     return ary;
 }
 
+/*
+ * call-seq:
+ *    cert.add_extension(extension) => extension
+ */
 static VALUE 
 ossl_x509_add_extension(VALUE self, VALUE extension)
 {
diff --git a/ext/openssl/ossl_x509name.c b/ext/openssl/ossl_x509name.c
index 7af3b689dd..c1164644e4 100644
--- a/ext/openssl/ossl_x509name.c
+++ b/ext/openssl/ossl_x509name.c
@@ -109,6 +109,13 @@ ossl_x509name_init_i(VALUE i, VALUE args)
     return Qnil;
 }
 
+/*
+ * call-seq:
+ *    X509::Name.new => name
+ *    X509::Name.new(string) => name
+ *    X509::Name.new(dn) => name
+ *    X509::Name.new(dn, template) => name
+ */
 static VALUE
 ossl_x509name_initialize(int argc, VALUE *argv, VALUE self)
 {
@@ -141,6 +148,10 @@ ossl_x509name_initialize(int argc, VALUE *argv, VALUE self)
     return self;
 }
 
+/*
+ * call-seq:
+ *    name.add_entry(oid, value [, type]) => self
+ */
 static
 VALUE ossl_x509name_add_entry(int argc, VALUE *argv, VALUE self)
 {
@@ -175,6 +186,11 @@ ossl_x509name_to_s_old(VALUE self)
     return str;
 }
 
+/*
+ * call-seq:
+ *    name.to_s => string
+ *    name.to_s(integer) => string
+ */
 static VALUE
 ossl_x509name_to_s(int argc, VALUE *argv, VALUE self)
 {
@@ -199,6 +215,10 @@ ossl_x509name_to_s(int argc, VALUE *argv, VALUE self)
     return str;
 }
 
+/*
+ * call-seq:
+ *    name.to_a => [[name, data, type], ...]
+ */
 static VALUE 
 ossl_x509name_to_a(VALUE self)
 {
@@ -266,6 +286,10 @@ ossl_x509name_eql(VALUE self, VALUE other)
     return (result == 0) ? Qtrue : Qfalse;
 }
 
+/*
+ * call-seq:
+ *    name.hash => integer
+ */
 static VALUE
 ossl_x509name_hash(VALUE self)
 {
@@ -279,6 +303,10 @@ ossl_x509name_hash(VALUE self)
     return ULONG2NUM(hash);
 }
 
+/*
+ * call-seq:
+ *    name.to_der => string
+ */
 static VALUE
 ossl_x509name_to_der(VALUE self)
 {
diff --git a/ext/openssl/ossl_x509store.c b/ext/openssl/ossl_x509store.c
index 64f5bca831..24a6625ee4 100644
--- a/ext/openssl/ossl_x509store.c
+++ b/ext/openssl/ossl_x509store.c
@@ -118,11 +118,18 @@ ossl_x509store_set_vfy_cb(VALUE self, VALUE cb)
     return cb;
 }
 
+
+/*
+ * call-seq:
+ *    X509::Store.new => store
+ *
+ */
 static VALUE
 ossl_x509store_initialize(int argc, VALUE *argv, VALUE self)
 {
     X509_STORE *store;
 
+/* BUG: This method takes any number of arguments but appears to ignore them. */
     GetX509Store(self, store);
     X509_STORE_set_verify_cb_func(store, ossl_verify_cb);
     ossl_x509store_set_vfy_cb(self, Qnil);
@@ -550,6 +557,10 @@ ossl_x509stctx_set_trust(VALUE self, VALUE trust)
     return trust;
 }
 
+/*
+ * call-seq:
+ *    storectx.time = time => time
+ */
 static VALUE
 ossl_x509stctx_set_time(VALUE self, VALUE time)
 {