summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authoremboss <emboss@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2011-10-20 17:22:09 +0000
committeremboss <emboss@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2011-10-20 17:22:09 +0000
commitb878cfa971870065e5a47cbe54758fe641a1cbf4 (patch)
tree06f4fdee1ea2ca95b5093e6fa7a6eb99cb4a757f
parent402c8cf9d1f67e326f41dc003f3d9ca6924810ec (diff)
* 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
-rw-r--r--ChangeLog5
-rw-r--r--ext/openssl/ossl_ns_spki.c125
-rw-r--r--test/openssl/test_ns_spki.rb1
3 files changed, 128 insertions, 3 deletions
diff --git a/ChangeLog b/ChangeLog
index 069f12a..63f7edc 100644
--- a/ChangeLog
+++ b/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):
diff --git a/ext/openssl/ossl_ns_spki.c b/ext/openssl/ossl_ns_spki.c
index acfc028..b80984c 100644
--- a/ext/openssl/ossl_ns_spki.c
+++ b/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()
{
diff --git a/test/openssl/test_ns_spki.rb b/test/openssl/test_ns_spki.rb
index 3bcf3e6..7cddefa 100644
--- a/test/openssl/test_ns_spki.rb
+++ b/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