summaryrefslogtreecommitdiff
path: root/ext/openssl/ossl_ns_spki.c
diff options
context:
space:
mode:
Diffstat (limited to 'ext/openssl/ossl_ns_spki.c')
-rw-r--r--ext/openssl/ossl_ns_spki.c125
1 files changed, 122 insertions, 3 deletions
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()
{