* ext/openssl/ossl_ns_spki.c: Complete documentation.

* test/openssl/test_ns_spki.rb: Integrate SPKI#to_text.


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

ChangeLog

@@ -1,3 +1,8 @@
+Fri Oct 21 02:11:00 2011  Martin Bosslet  <Martin.Bosslet@googlemail.com>
+
+	* ext/openssl/ossl_ns_spki.c: Complete documentation.
+	* test/openssl/test_ns_spki.rb: Integrate SPKI#to_text.
+
 Thu Oct 20 22:47:28 2011  NAKAMURA Usaku  <usa@ruby-lang.org>
 
 	* win32/win32.c (socklist_insert, socklist_lookup, socklist_delete):

ext/openssl/ossl_ns_spki.c

@@ -51,6 +51,13 @@ ossl_spki_alloc(VALUE klass)
     return obj;
 }
 
+/*
+ * call-seq:
+ *    SPKI.new([request]) => spki
+ *
+ * === Parameters
+ * * +request+ - optional raw request, either in PEM or DER format.
+ */
 static VALUE
 ossl_spki_initialize(int argc, VALUE *argv, VALUE self)
 {
@@ -75,6 +82,12 @@ ossl_spki_initialize(int argc, VALUE *argv, VALUE self)
     return self;
 }
 
+/*
+ * call-seq:
+ *    spki.to_der => DER-encoded string
+ *
+ * Returns the DER encoding of this SPKI.
+ */
 static VALUE
 ossl_spki_to_der(VALUE self)
 {
@@ -95,6 +108,12 @@ ossl_spki_to_der(VALUE self)
     return str;
 }
 
+/*
+ * call-seq:
+ *    spki.to_pem => PEM-encoded string
+ *
+ * Returns the PEM encoding of this SPKI.
+ */
 static VALUE
 ossl_spki_to_pem(VALUE self)
 {
@@ -111,6 +130,13 @@ ossl_spki_to_pem(VALUE self)
     return str;
 }
 
+/*
+ * call-seq:
+ *    spki.to_text => string
+ *
+ * Returns a textual representation of this SPKI, useful for debugging
+ * purposes.
+ */
 static VALUE
 ossl_spki_print(VALUE self)
 {
@@ -134,6 +160,13 @@ ossl_spki_print(VALUE self)
     return str;
 }
 
+/*
+ * call-seq:
+ *    spki.public_key => pkey
+ *
+ * Returns the public key associated with the SPKI, an instance of
+ * OpenSSL::PKey.
+ */
 static VALUE
 ossl_spki_get_public_key(VALUE self)
 {
@@ -148,6 +181,17 @@ ossl_spki_get_public_key(VALUE self)
     return ossl_pkey_new(pkey); /* NO DUP - OK */
 }
 
+/*
+ * call-seq:
+ *    spki.public_key = pub => pkey
+ *
+ * === Parameters
+ * * +pub+ - the public key to be set for this instance
+ *
+ * Sets the public key to be associated with the SPKI, an instance of
+ * OpenSSL::PKey. This should be the public key corresponding to the
+ * private key used for signing the SPKI.
+ */
 static VALUE
 ossl_spki_set_public_key(VALUE self, VALUE key)
 {
@@ -161,6 +205,12 @@ ossl_spki_set_public_key(VALUE self, VALUE key)
     return key;
 }
 
+/*
+ * call-seq:
+ *    spki.challenge => string
+ *
+ * Returns the challenge string associated with this SPKI.
+ */
 static VALUE
 ossl_spki_get_challenge(VALUE self)
 {
@@ -176,6 +226,16 @@ ossl_spki_get_challenge(VALUE self)
 		      spki->spkac->challenge->length);
 }
 
+/*
+ * call-seq:
+ *    spki.challenge = str => string
+ *
+ * === Parameters
+ * * +str+ - the challenge string to be set for this instance
+ *
+ * Sets the challenge to be associated with the SPKI. May be used by the
+ * server, e.g. to prevent replay.
+ */
 static VALUE
 ossl_spki_set_challenge(VALUE self, VALUE str)
 {
@@ -191,6 +251,19 @@ ossl_spki_set_challenge(VALUE self, VALUE str)
     return str;
 }
 
+/*
+ * call-seq:
+ *    spki.sign(key, digest) => spki
+ *
+ * === Parameters
+ * * +key+ - the private key to be used for signing this instance
+ * * +digest+ - the digest to be used for signing this instance
+ *
+ * To sign an SPKI, the private key corresponding to the public key set
+ * for this instance should be used, in addition to a digest algorithm in
+ * the form of an OpenSSL::Digest. The private key should be an instance of
+ * OpenSSL::PKey.
+ */
 static VALUE
 ossl_spki_sign(VALUE self, VALUE key, VALUE digest)
 {
@@ -209,7 +282,14 @@ ossl_spki_sign(VALUE self, VALUE key, VALUE digest)
 }
 
 /*
- * Checks that cert signature is made with PRIVversion of this PUBLIC 'key'
+ * call-seq:
+ *    spki.verify(key) => boolean
+ *
+ * === Parameters
+ * * +key+ - the public key to be used for verifying the SPKI signature
+ *
+ * Returns +true+ if the signature is valid, +false+ otherwise. To verify an
+ * SPKI, the public key contained within the SPKI should be used.
  */
 static VALUE
 ossl_spki_verify(VALUE self, VALUE key)
@@ -231,15 +311,54 @@ ossl_spki_verify(VALUE self, VALUE key)
 /* Document-class: OpenSSL::Netscape::SPKI
  *
  * A Simple Public Key Infrastructure implementation (pronounced "spookey").
- * See {RFC 2692}[http://tools.ietf.org/html/rfc2692] and {RFC
- * 2693}[http://tools.ietf.org/html/rfc2692] for details.
+ * The structure is defined as
+ *   PublicKeyAndChallenge ::= SEQUENCE {
+ *     spki SubjectPublicKeyInfo,
+ *     challenge IA5STRING
+ *   }
+ *
+ *   SignedPublicKeyAndChallenge ::= SEQUENCE {
+ *     publicKeyAndChallenge PublicKeyAndChallenge,
+ *     signatureAlgorithm AlgorithmIdentifier,
+ *     signature BIT STRING
+ *   }
+ * where the definitions of SubjectPublicKeyInfo and AlgorithmIdentifier can
+ * be found in RFC5280. SPKI is typically used in browsers for generating
+ * a public/private key pair and a subsequent certificate request, using
+ * the HTML <keygen> element.
+ *
+ * == Examples
+ *
+ * === Creating an SPKI
+ *   key = OpenSSL::PKey::RSA.new 2048
+ *   spki = OpenSSL::Netscape::SPKI.new
+ *   spki.challenge = "RandomChallenge"
+ *   spki.public_key = key.public_key
+ *   spki.sign(key, OpenSSL::Digest::SHA256.new)
+ *   #send a request containing this to a server generating a certificate
+ * === Verifiying an SPKI request
+ *   request = #...
+ *   spki = OpenSSL::Netscape::SPKI.new request
+ *   unless spki.verify(spki.public_key)
+ *     # signature is invalid
+ *   end
+ *   #proceed
  */
 
 /* Document-module: OpenSSL::Netscape
  *
  * OpenSSL::Netscape is a namespace for SPKI (Simple Public Key
  * Infrastructure) which implements Signed Public Key and Challenge.
+ * See {RFC 2692}[http://tools.ietf.org/html/rfc2692] and {RFC
+ * 2693}[http://tools.ietf.org/html/rfc2692] for details.
  */
+
+/* Document-class: OpenSSL::Netscape::SPKIError
+ *
+ * Generic Exception class that is raised if an error occurs during an
+ * operation on an instance of OpenSSL::Netscape::SPKI.
+ */
+
 void
 Init_ossl_ns_spki()
 {

test/openssl/test_ns_spki.rb

@@ -30,6 +30,7 @@ class OpenSSL::TestNSSPI < Test::Unit::TestCase
     assert_equal("RandomString", spki.challenge)
     assert_equal(key1.public_key.to_der, spki.public_key.to_der)
     assert(spki.verify(spki.public_key))
+    assert_not_nil(spki.to_text)
   end
 
   def test_decode_data