diff options
Diffstat (limited to 'ext/openssl')
| -rw-r--r-- | ext/openssl/ossl_ns_spki.c | 125 |
1 files changed, 122 insertions, 3 deletions
diff --git a/ext/openssl/ossl_ns_spki.c b/ext/openssl/ossl_ns_spki.c index acfc028a5e..b80984cfee 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() { |