From 41fa6056ba08e7a94d60e10825d271fbd1fa5596 Mon Sep 17 00:00:00 2001 From: technorama Date: Thu, 29 Mar 2007 17:29:03 +0000 Subject: * ext/openssl/ossl_{bn,cipher,digest,hmac,rand,pkey_{dh,dsa,rsa}}.c: Add Documentation for various methods. * ext/openssl/lib/openssl/cipher.rb: Ditto * ext/openssl/ossl_bn.c: add lshift! and rshift! methods. * ext/openssl/ossl_digest.c: GetDigestPtr() also accept a string. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@12128 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ext/openssl/lib/openssl/cipher.rb | 4 ++ ext/openssl/ossl_bn.c | 79 +++++++++++++++++++++- ext/openssl/ossl_cipher.c | 137 +++++++++++++++++++++++++++++++++++++- ext/openssl/ossl_digest.c | 59 +++++++++++++++- ext/openssl/ossl_hmac.c | 31 +++++++++ ext/openssl/ossl_pkey_dh.c | 88 +++++++++++++++++++++--- ext/openssl/ossl_pkey_dsa.c | 75 +++++++++++++++++++-- ext/openssl/ossl_pkey_rsa.c | 86 +++++++++++++++++++++++- ext/openssl/ossl_rand.c | 30 +++++++++ 9 files changed, 570 insertions(+), 19 deletions(-) diff --git a/ext/openssl/lib/openssl/cipher.rb b/ext/openssl/lib/openssl/cipher.rb index 049533d06b..45cf6ac93e 100644 --- a/ext/openssl/lib/openssl/cipher.rb +++ b/ext/openssl/lib/openssl/cipher.rb @@ -42,12 +42,16 @@ module OpenSSL } class Cipher + # Generate, set, and return a random key. + # You must call cipher.encrypt or cipher.decrypt before calling this method. def random_key str = OpenSSL::Random.random_bytes(self.key_len) self.key = str return str end + # Generate, set, and return a random iv. + # You must call cipher.encrypt or cipher.decrypt before calling this method. def random_iv str = OpenSSL::Random.random_bytes(self.iv_len) self.iv = str diff --git a/ext/openssl/ossl_bn.c b/ext/openssl/ossl_bn.c index 5a77ffe84e..ec1f37222a 100644 --- a/ext/openssl/ossl_bn.c +++ b/ext/openssl/ossl_bn.c @@ -233,6 +233,11 @@ ossl_bn_coerce(VALUE self, VALUE other) } #define BIGNUM_BOOL1(func) \ + /* \ + * call-seq: \ + * bn.##func -> true | false \ + * \ + */ \ static VALUE \ ossl_bn_##func(VALUE self) \ { \ @@ -248,6 +253,11 @@ BIGNUM_BOOL1(is_one); BIGNUM_BOOL1(is_odd); #define BIGNUM_1c(func) \ + /* \ + * call-seq: \ + * bn.##func -> aBN \ + * \ + */ \ static VALUE \ ossl_bn_##func(VALUE self) \ { \ @@ -267,6 +277,11 @@ BIGNUM_BOOL1(is_odd); BIGNUM_1c(sqr); #define BIGNUM_2(func) \ + /* \ + * call-seq: \ + * bn.##func(bn2) -> aBN \ + * \ + */ \ static VALUE \ ossl_bn_##func(VALUE self, VALUE other) \ { \ @@ -287,6 +302,11 @@ BIGNUM_2(add); BIGNUM_2(sub); #define BIGNUM_2c(func) \ + /* \ + * call-seq: \ + * bn.##func(bn2) -> aBN \ + * \ + */ \ static VALUE \ ossl_bn_##func(VALUE self, VALUE other) \ { \ @@ -337,6 +357,11 @@ ossl_bn_div(VALUE self, VALUE other) } #define BIGNUM_3c(func) \ + /* \ + * call-seq: \ + * bn.##func(bn1, bn2) -> aBN \ + * \ + */ \ static VALUE \ ossl_bn_##func(VALUE self, VALUE other1, VALUE other2) \ { \ @@ -360,6 +385,11 @@ BIGNUM_3c(mod_mul); BIGNUM_3c(mod_exp); #define BIGNUM_BIT(func) \ + /* \ + * call-seq: \ + * bn.##func(bit) -> self \ + * \ + */ \ static VALUE \ ossl_bn_##func(VALUE self, VALUE bit) \ { \ @@ -389,6 +419,11 @@ ossl_bn_is_bit_set(VALUE self, VALUE bit) } #define BIGNUM_SHIFT(func) \ + /* \ + * call-seq: \ + * bn.##func(bits) -> aBN \ + * \ + */ \ static VALUE \ ossl_bn_##func(VALUE self, VALUE bits) \ { \ @@ -410,7 +445,32 @@ ossl_bn_is_bit_set(VALUE self, VALUE bit) BIGNUM_SHIFT(lshift); BIGNUM_SHIFT(rshift); +#define BIGNUM_SELF_SHIFT(func) \ + /* \ + * call-seq: \ + * bn.##func!(bits) -> self \ + * \ + */ \ + static VALUE \ + ossl_bn_self_##func(VALUE self, VALUE bits) \ + { \ + BIGNUM *bn; \ + int b; \ + b = NUM2INT(bits); \ + GetBN(self, bn); \ + if (!BN_##func(bn, bn, b)) \ + ossl_raise(eBNError, NULL); \ + return self; \ + } +BIGNUM_SELF_SHIFT(lshift); +BIGNUM_SELF_SHIFT(rshift); + #define BIGNUM_RAND(func) \ + /* \ + * call-seq: \ + * BN.##func(bits [, fill [, odd]]) -> aBN \ + * \ + */ \ static VALUE \ ossl_bn_s_##func(int argc, VALUE *argv, VALUE klass) \ { \ @@ -440,6 +500,11 @@ BIGNUM_RAND(rand); BIGNUM_RAND(pseudo_rand); #define BIGNUM_RAND_RANGE(func) \ + /* \ + * call-seq: \ + * BN.##func(range) -> aBN \ + * \ + */ \ static VALUE \ ossl_bn_s_##func##_range(VALUE klass, VALUE range) \ { \ @@ -493,6 +558,11 @@ ossl_bn_s_generate_prime(int argc, VALUE *argv, VALUE klass) } #define BIGNUM_NUM(func) \ + /* \ + * call-seq: \ + * bn.##func -> integer \ + * \ + */ \ static VALUE \ ossl_bn_##func(VALUE self) \ { \ @@ -522,6 +592,11 @@ ossl_bn_copy(VALUE self, VALUE other) } #define BIGNUM_CMP(func) \ + /* \ + * call-seq: \ + * bn.##func(bn2) -> integer \ + * \ + */ \ static VALUE \ ossl_bn_##func(VALUE self, VALUE other) \ { \ @@ -676,8 +751,10 @@ Init_ossl_bn() rb_define_method(cBN, "bit_set?", ossl_bn_is_bit_set, 1); rb_define_method(cBN, "mask_bits!", ossl_bn_mask_bits, 1); rb_define_method(cBN, "<<", ossl_bn_lshift, 1); - /* lshift1 - DON'T IMPL. */ rb_define_method(cBN, ">>", ossl_bn_rshift, 1); + rb_define_method(cBN, "lshift!", ossl_bn_self_lshift, 1); + rb_define_method(cBN, "rshift!", ossl_bn_self_rshift, 1); + /* lshift1 - DON'T IMPL. */ /* rshift1 - DON'T IMPL. */ /* diff --git a/ext/openssl/ossl_cipher.c b/ext/openssl/ossl_cipher.c index b50bee71c5..e260a4b04f 100644 --- a/ext/openssl/ossl_cipher.c +++ b/ext/openssl/ossl_cipher.c @@ -84,6 +84,14 @@ ossl_cipher_alloc(VALUE klass) return obj; } +/* + * call-seq: + * Cipher.new(string) -> cipher + * + * The string must contain a valid cipher name like "AES-128-CBC" or "3DES". + * + * A list of cipher names is available by calling OpenSSL::Cipher.ciphers. + */ static VALUE ossl_cipher_initialize(VALUE self, VALUE str) { @@ -124,6 +132,12 @@ add_cipher_name_to_ary(const OBJ_NAME *name, VALUE ary) return NULL; } +/* + * call-seq: + * Cipher.ciphers -> array[string...] + * + * Returns the names of all available ciphers in an array. + */ static VALUE ossl_s_ciphers(VALUE self) { @@ -141,6 +155,12 @@ ossl_s_ciphers(VALUE self) #endif } +/* + * call-seq: + * cipher.reset -> self + * + * Internally calls EVP_CipherInit_ex(ctx, NULL, NULL, NULL, NULL, -1). + */ static VALUE ossl_cipher_reset(VALUE self) { @@ -197,18 +217,54 @@ ossl_cipher_init(int argc, VALUE *argv, VALUE self, int mode) return self; } +/* + * call-seq: + * cipher.encrypt -> self + * + * Make sure to call .encrypt or .decrypt before using any of the following methods: + * * [key=, iv=, random_key, random_iv, pkcs5_keyivgen] + * + * Internally calls EVP_CipherInit_ex(ctx, NULL, NULL, NULL, NULL, 1). + */ static VALUE ossl_cipher_encrypt(int argc, VALUE *argv, VALUE self) { return ossl_cipher_init(argc, argv, self, 1); } +/* + * call-seq: + * cipher.decrypt -> self + * + * Make sure to call .encrypt or .decrypt before using any of the following methods: + * * [key=, iv=, random_key, random_iv, pkcs5_keyivgen] + * + * Internally calls EVP_CipherInit_ex(ctx, NULL, NULL, NULL, NULL, 0). + */ static VALUE ossl_cipher_decrypt(int argc, VALUE *argv, VALUE self) { return ossl_cipher_init(argc, argv, self, 0); } +/* + * call-seq: + * cipher.pkcs5_keyivgen(pass [, salt [, iterations [, digest]]] ) -> nil + * + * Generates and sets the key/iv based on a password. + * + * WARNING: This method is only PKCS5 v1.5 compliant when using RC2, RC4-40, or DES + * with MD5 or SHA1. Using anything else (like AES) will generate the key/iv using an + * OpenSSL specific method. Use a PKCS5 v2 key generation method instead. + * + * === Parameters + * +salt+ must be an 8 byte string if provided. + * +iterations+ is a integer with a default of 2048. + * +digest+ is a Digest object that defaults to 'MD5' + * + * A minimum of 1000 iterations is recommended. + * + */ static VALUE ossl_cipher_pkcs5_keyivgen(int argc, VALUE *argv, VALUE self) { @@ -239,6 +295,11 @@ ossl_cipher_pkcs5_keyivgen(int argc, VALUE *argv, VALUE self) return Qnil; } +/* + * call-seq: + * cipher.update(string) -> aString + * + */ static VALUE ossl_cipher_update(VALUE self, VALUE data) { @@ -261,6 +322,14 @@ ossl_cipher_update(VALUE self, VALUE data) return str; } +/* + * call-seq: + * cipher.final -> aString + * + * Returns the remaining data held in the cipher object. Further calls to update() or final() will return garbage. + * + * See EVP_CipherFinal_ex for further information. + */ static VALUE ossl_cipher_final(VALUE self) { @@ -278,6 +347,12 @@ ossl_cipher_final(VALUE self) return str; } +/* + * call-seq: + * cipher.name -> string + * + * Returns the name of the cipher which may differ slightly from the original name provided. + */ static VALUE ossl_cipher_name(VALUE self) { @@ -288,6 +363,14 @@ ossl_cipher_name(VALUE self) return rb_str_new2(EVP_CIPHER_name(EVP_CIPHER_CTX_cipher(ctx))); } +/* + * call-seq: + * cipher.key = string -> string + * + * Sets the cipher key. + * + * Only call this method after calling cipher.encrypt or cipher.decrypt. + */ static VALUE ossl_cipher_set_key(VALUE self, VALUE key) { @@ -305,6 +388,14 @@ ossl_cipher_set_key(VALUE self, VALUE key) return key; } +/* + * call-seq: + * cipher.iv = string -> string + * + * Sets the cipher iv. + * + * Only call this method after calling cipher.encrypt or cipher.decrypt. + */ static VALUE ossl_cipher_set_iv(VALUE self, VALUE iv) { @@ -322,6 +413,18 @@ ossl_cipher_set_iv(VALUE self, VALUE iv) return iv; } + +/* + * call-seq: + * cipher.key_length = integer -> integer + * + * Sets the key length of the cipher. If the cipher is a fixed length cipher then attempting to set the key + * length to any value other than the fixed value is an error. + * + * Under normal circumstances you do not need to call this method (and probably shouldn't). + * + * See EVP_CIPHER_CTX_set_key_length for further information. + */ static VALUE ossl_cipher_set_key_length(VALUE self, VALUE key_length) { @@ -335,6 +438,16 @@ ossl_cipher_set_key_length(VALUE self, VALUE key_length) return key_length; } +/* + * call-seq: + * cipher.padding = integer -> integer + * + * Enables or disables padding. By default encryption operations are padded using standard block padding and the + * padding is checked and removed when decrypting. If the pad parameter is zero then no padding is performed, the + * total amount of data encrypted or decrypted must then be a multiple of the block size or an error will occur. + * + * See EVP_CIPHER_CTX_set_padding for further information. + */ static VALUE ossl_cipher_set_padding(VALUE self, VALUE padding) { @@ -363,6 +476,27 @@ CIPHER_0ARG_INT(key_length) CIPHER_0ARG_INT(iv_length) CIPHER_0ARG_INT(block_size) +#if 0 +/* + * call-seq: + * cipher.key_length -> integer + * + */ +static VALUE ossl_cipher_key_length() { } +/* + * call-seq: + * cipher.iv_length -> integer + * + */ +static VALUE ossl_cipher_iv_length() { } +/* + * call-seq: + * cipher.block_size -> integer + * + */ +static VALUE ossl_cipher_block_size() { } +#endif + /* * INIT */ @@ -372,7 +506,6 @@ Init_ossl_cipher(void) #if 0 /* let rdoc know about mOSSL */ mOSSL = rb_define_module("OpenSSL"); #endif - mCipher = rb_define_module_under(mOSSL, "Cipher"); eCipherError = rb_define_class_under(mOSSL, "CipherError", eOSSLError); cCipher = rb_define_class_under(mCipher, "Cipher", rb_cObject); @@ -395,4 +528,6 @@ Init_ossl_cipher(void) rb_define_method(cCipher, "iv_len", ossl_cipher_iv_length, 0); rb_define_method(cCipher, "block_size", ossl_cipher_block_size, 0); rb_define_method(cCipher, "padding=", ossl_cipher_set_padding, 1); + + rb_define_const(mCipher, "PKCS5_SALT_LEN", PKCS5_SALT_LEN); } diff --git a/ext/openssl/ossl_digest.c b/ext/openssl/ossl_digest.c index 867fc47095..9b280a3d4d 100644 --- a/ext/openssl/ossl_digest.c +++ b/ext/openssl/ossl_digest.c @@ -36,11 +36,23 @@ static VALUE ossl_digest_alloc(VALUE klass); const EVP_MD * GetDigestPtr(VALUE obj) { - EVP_MD_CTX *ctx; + const EVP_MD *md; + + if (TYPE(obj) == T_STRING) { + const char *name = STR2CSTR(obj); + + md = EVP_get_digestbyname(name); + if (!md) + ossl_raise(rb_eRuntimeError, "Unsupported digest algorithm (%s).", name); + } else { + EVP_MD_CTX *ctx; + + SafeGetDigest(obj, ctx); - SafeGetDigest(obj, ctx); + md = EVP_MD_CTX_md(ctx); /*== ctx->digest*/ + } - return EVP_MD_CTX_md(ctx); /*== ctx->digest*/ + return md; } VALUE @@ -77,6 +89,11 @@ ossl_digest_alloc(VALUE klass) VALUE ossl_digest_update(VALUE, VALUE); +/* + * call-seq: + * Digest.new(string) -> digest + * + */ static VALUE ossl_digest_initialize(int argc, VALUE *argv, VALUE self) { @@ -118,6 +135,11 @@ ossl_digest_copy(VALUE self, VALUE other) return self; } +/* + * call-seq: + * digest.reset -> self + * + */ static VALUE ossl_digest_reset(VALUE self) { @@ -129,6 +151,11 @@ ossl_digest_reset(VALUE self) return self; } +/* + * call-seq: + * digest.update(string) -> aString + * + */ VALUE ossl_digest_update(VALUE self, VALUE data) { @@ -157,6 +184,11 @@ digest_final(EVP_MD_CTX *ctx, char **buf, int *buf_len) EVP_MD_CTX_cleanup(&final); } +/* + * call-seq: + * digest.final -> aString + * + */ static VALUE ossl_digest_digest(VALUE self) { @@ -172,6 +204,11 @@ ossl_digest_digest(VALUE self) return digest; } +/* + * call-seq: + * digest.hexdigest -> aString + * + */ static VALUE ossl_digest_hexdigest(VALUE self) { @@ -212,6 +249,11 @@ ossl_digest_s_hexdigest(VALUE klass, VALUE str, VALUE data) return ossl_digest_hexdigest(obj); } +/* + * call-seq: + * digest1 == digest2 -> true | false + * + */ static VALUE ossl_digest_equal(VALUE self, VALUE other) { @@ -238,6 +280,11 @@ ossl_digest_equal(VALUE self, VALUE other) return Qfalse; } +/* + * call-seq: + * digest.name -> string + * + */ static VALUE ossl_digest_name(VALUE self) { @@ -248,6 +295,12 @@ ossl_digest_name(VALUE self) return rb_str_new2(EVP_MD_name(EVP_MD_CTX_md(ctx))); } +/* + * call-seq: + * digest.size -> integer + * + * Returns the output size of the digest. + */ static VALUE ossl_digest_size(VALUE self) { diff --git a/ext/openssl/ossl_hmac.c b/ext/openssl/ossl_hmac.c index b06823a932..84d378f732 100644 --- a/ext/openssl/ossl_hmac.c +++ b/ext/openssl/ossl_hmac.c @@ -57,6 +57,12 @@ ossl_hmac_alloc(VALUE klass) return obj; } + +/* + * call-seq: + * HMAC.new(key, digest) -> hmac + * + */ static VALUE ossl_hmac_initialize(VALUE self, VALUE key, VALUE digest) { @@ -87,6 +93,11 @@ ossl_hmac_copy(VALUE self, VALUE other) return self; } +/* + * call-seq: + * hmac.update(string) -> self + * + */ static VALUE ossl_hmac_update(VALUE self, VALUE data) { @@ -116,6 +127,11 @@ hmac_final(HMAC_CTX *ctx, char **buf, int *buf_len) HMAC_CTX_cleanup(&final); } +/* + * call-seq: + * hmac.digest -> aString + * + */ static VALUE ossl_hmac_digest(VALUE self) { @@ -131,6 +147,11 @@ ossl_hmac_digest(VALUE self) return digest; } +/* + * call-seq: + * hmac.hexdigest -> aString + * + */ static VALUE ossl_hmac_hexdigest(VALUE self) { @@ -151,6 +172,11 @@ ossl_hmac_hexdigest(VALUE self) return hexdigest; } +/* + * call-seq: + * HMAC.digest(digest, key, data) -> aString + * + */ static VALUE ossl_hmac_s_digest(VALUE klass, VALUE digest, VALUE key, VALUE data) { @@ -165,6 +191,11 @@ ossl_hmac_s_digest(VALUE klass, VALUE digest, VALUE key, VALUE data) return rb_str_new(buf, buf_len); } +/* + * call-seq: + * HMAC.digest(digest, key, data) -> aString + * + */ static VALUE ossl_hmac_s_hexdigest(VALUE klass, VALUE digest, VALUE key, VALUE data) { diff --git a/ext/openssl/ossl_pkey_dh.c b/ext/openssl/ossl_pkey_dh.c index a9d708bd55..3614914680 100644 --- a/ext/openssl/ossl_pkey_dh.c +++ b/ext/openssl/ossl_pkey_dh.c @@ -99,6 +99,15 @@ dh_generate(int size, int gen) return dh; } +/* + * call-seq: + * DH.generate(size [, generator]) -> dh + * + * === Parameters + * * +size+ is an integer representing the desired key size. Keys smaller than 1024 should be considered insecure. + * * +generator+ is a small number > 1, typically 2 or 5. + * + */ static VALUE ossl_dh_s_generate(int argc, VALUE *argv, VALUE klass) { @@ -119,6 +128,21 @@ ossl_dh_s_generate(int argc, VALUE *argv, VALUE klass) return obj; } +/* + * call-seq: + * DH.new([size [, generator] | string]) -> dh + * + * === Parameters + * * +size+ is an integer representing the desired key size. Keys smaller than 1024 should be considered insecure. + * * +generator+ is a small number > 1, typically 2 or 5. + * * +string+ contains the DER or PEM encoded key. + * + * === Examples + * * DH.new -> dh + * * DH.new(1024) -> dh + * * DH.new(1024, 5) -> dh + * * DH.new(File.read('key.pem')) -> dh + */ static VALUE ossl_dh_initialize(int argc, VALUE *argv, VALUE self) { @@ -158,19 +182,26 @@ ossl_dh_initialize(int argc, VALUE *argv, VALUE self) return self; } +/* + * call-seq: + * dh.public? -> true | false + * + */ static VALUE ossl_dh_is_public(VALUE self) { EVP_PKEY *pkey; GetPKeyDH(self, pkey); - /* - * Do we need to check dhp->dh->public_pkey? - * return Qtrue; - */ + return (pkey->pkey.dh->pub_key) ? Qtrue : Qfalse; } +/* + * call-seq: + * dh.private? -> true | false + * + */ static VALUE ossl_dh_is_private(VALUE self) { @@ -181,6 +212,11 @@ ossl_dh_is_private(VALUE self) return (DH_PRIVATE(pkey->pkey.dh)) ? Qtrue : Qfalse; } +/* + * call-seq: + * dh.to_pem -> aString + * + */ static VALUE ossl_dh_export(VALUE self) { @@ -201,6 +237,11 @@ ossl_dh_export(VALUE self) return str; } +/* + * call-seq: + * dh.to_der -> aString + * + */ static VALUE ossl_dh_to_der(VALUE self) { @@ -222,6 +263,9 @@ ossl_dh_to_der(VALUE self) } /* + * call-seq: + * dh.params -> hash + * * Stores all parameters of key to the hash * INSECURE: PRIVATE INFORMATIONS CAN LEAK OUT!!! * Don't use :-)) (I's up to you) @@ -245,6 +289,9 @@ ossl_dh_get_params(VALUE self) } /* + * call-seq: + * dh.to_text -> aString + * * Prints all parameters of key to buffer * INSECURE: PRIVATE INFORMATIONS CAN LEAK OUT!!! * Don't use :-)) (I's up to you) @@ -270,7 +317,10 @@ ossl_dh_to_text(VALUE self) } /* - * Makes new instance DH PUBLIC_KEY from PRIVATE_KEY + * call-seq: + * dh.public_key -> aDH + * + * Makes new instance DH PUBLIC_KEY from PRIVATE_KEY */ static VALUE ossl_dh_to_public_key(VALUE self) @@ -290,6 +340,11 @@ ossl_dh_to_public_key(VALUE self) return obj; } +/* + * call-seq: + * dh.check_params -> true | false + * + */ static VALUE ossl_dh_check_params(VALUE self) { @@ -307,6 +362,11 @@ ossl_dh_check_params(VALUE self) return codes == 0 ? Qtrue : Qfalse; } +/* + * call-seq: + * dh.generate_key -> self + * + */ static VALUE ossl_dh_generate_key(VALUE self) { @@ -321,6 +381,18 @@ ossl_dh_generate_key(VALUE self) return self; } +/* + * call-seq: + * dh.compute_key(pub_bn) -> aString + * + * === Parameters + * * +pub_bn+ is a OpenSSL::BN. + * + * Returns aString containing a shared secret computed from the other parties public value. + * + * See DH_compute_key() for further information. + * + */ static VALUE ossl_dh_compute_key(VALUE self, VALUE pub) { @@ -411,9 +483,9 @@ ossl_create_dh(unsigned char *p, size_t plen, unsigned char *g, size_t glen) return dh; } -/* - * INIT - */ + /* + * TEST + */ void Init_ossl_dh() { diff --git a/ext/openssl/ossl_pkey_dsa.c b/ext/openssl/ossl_pkey_dsa.c index 80cadb1cb6..95dc426366 100644 --- a/ext/openssl/ossl_pkey_dsa.c +++ b/ext/openssl/ossl_pkey_dsa.c @@ -99,6 +99,14 @@ dsa_generate(int size) return dsa; } +/* + * call-seq: + * DSA.generate(size) -> dsa + * + * === Parameters + * * +size+ is an integer representing the desired key size. + * + */ static VALUE ossl_dsa_s_generate(VALUE klass, VALUE size) { @@ -113,6 +121,22 @@ ossl_dsa_s_generate(VALUE klass, VALUE size) return obj; } +/* + * call-seq: + * DSA.new([size | string [, pass]) -> dsa + * + * === Parameters + * * +size+ is an integer representing the desired key size. + * * +string+ contains a DER or PEM encoded key. + * * +pass+ is a string that contains a optional password. + * + * === Examples + * * DSA.new -> dsa + * * DSA.new(1024) -> dsa + * * DSA.new(File.read('dsa.pem')) -> dsa + * * DSA.new(File.read('dsa.pem'), 'mypassword') -> dsa + * + */ static VALUE ossl_dsa_initialize(int argc, VALUE *argv, VALUE self) { @@ -163,6 +187,11 @@ ossl_dsa_initialize(int argc, VALUE *argv, VALUE self) return self; } +/* + * call-seq: + * dsa.public? -> true | false + * + */ static VALUE ossl_dsa_is_public(VALUE self) { @@ -170,13 +199,14 @@ ossl_dsa_is_public(VALUE self) GetPKeyDSA(self, pkey); - /* - * Do we need to check dsap->dsa->public_pkey? - * return Qtrue; - */ return (pkey->pkey.dsa->pub_key) ? Qtrue : Qfalse; } +/* + * call-seq: + * dsa.private? -> true | false + * + */ static VALUE ossl_dsa_is_private(VALUE self) { @@ -187,6 +217,19 @@ ossl_dsa_is_private(VALUE self) return (DSA_PRIVATE(self, pkey->pkey.dsa)) ? Qtrue : Qfalse; } +/* + * call-seq: + * dsa.to_pem([cipher, password]) -> aString + * + * === Parameters + * +cipher+ is an OpenSSL::Cipher. + * +password+ is a string containing your password. + * + * === Examples + * * DSA.to_pem -> aString + * * DSA.to_pem(cipher, 'mypassword') -> aString + * + */ static VALUE ossl_dsa_export(int argc, VALUE *argv, VALUE self) { @@ -224,6 +267,11 @@ ossl_dsa_export(int argc, VALUE *argv, VALUE self) return str; } +/* + * call-seq: + * dsa.to_der -> aString + * + */ static VALUE ossl_dsa_to_der(VALUE self) { @@ -250,6 +298,9 @@ ossl_dsa_to_der(VALUE self) } /* + * call-seq: + * dsa.params -> hash + * * Stores all parameters of key to the hash * INSECURE: PRIVATE INFORMATIONS CAN LEAK OUT!!! * Don't use :-)) (I's up to you) @@ -274,6 +325,9 @@ ossl_dsa_get_params(VALUE self) } /* + * call-seq: + * dsa.to_text -> aString + * * Prints all parameters of key to buffer * INSECURE: PRIVATE INFORMATIONS CAN LEAK OUT!!! * Don't use :-)) (I's up to you) @@ -299,6 +353,9 @@ ossl_dsa_to_text(VALUE self) } /* + * call-seq: + * dsa.public_key -> aDSA + * * Makes new instance DSA PUBLIC_KEY from PRIVATE_KEY */ static VALUE @@ -321,6 +378,11 @@ ossl_dsa_to_public_key(VALUE self) #define ossl_dsa_buf_size(pkey) (DSA_size((pkey)->pkey.dsa)+16) +/* + * call-seq: + * dsa.syssign(string) -> aString + * + */ static VALUE ossl_dsa_sign(VALUE self, VALUE data) { @@ -343,6 +405,11 @@ ossl_dsa_sign(VALUE self, VALUE data) return str; } +/* + * call-seq: + * dsa.sysverify(digest, sig) -> true | false + * + */ static VALUE ossl_dsa_verify(VALUE self, VALUE digest, VALUE sig) { diff --git a/ext/openssl/ossl_pkey_rsa.c b/ext/openssl/ossl_pkey_rsa.c index 1102ea1b59..783a77f6de 100644 --- a/ext/openssl/ossl_pkey_rsa.c +++ b/ext/openssl/ossl_pkey_rsa.c @@ -84,9 +84,19 @@ rsa_generate(int size, int exp) NULL); } +/* + * call-seq: + * RSA.generate(size [, exponent]) -> rsa + * + * === Parameters + * * +size+ is an integer representing the desired key size. Keys smaller than 1024 should be considered insecure. + * * +exponent+ is an odd number normally 3, 17, or 65537. + * + */ static VALUE ossl_rsa_s_generate(int argc, VALUE *argv, VALUE klass) { +/* why does this method exist? why can't initialize take an optional exponent? */ RSA *rsa; VALUE size, exp; VALUE obj; @@ -104,6 +114,20 @@ ossl_rsa_s_generate(int argc, VALUE *argv, VALUE klass) return obj; } +/* + * call-seq: + * RSA.new([size | encoded_key] [, pass]) -> rsa + * + * === Parameters + * * +size+ is an integer representing the desired key size. + * * +encoded_key+ is a string containing PEM or DER encoded key. + * * +pass+ is an optional string with the password to decrypt the encoded key. + * + * === Examples + * * RSA.new(2048) -> rsa + * * RSA.new(File.read("rsa.pem")) -> rsa + * * RSA.new(File.read("rsa.pem"), "mypassword") -> rsa + */ static VALUE ossl_rsa_initialize(int argc, VALUE *argv, VALUE self) { @@ -157,6 +181,13 @@ ossl_rsa_initialize(int argc, VALUE *argv, VALUE self) return self; } +/* + * call-seq: + * rsa.public? -> true + * + * The return value is always true since every private key is also a public key. + * + */ static VALUE ossl_rsa_is_public(VALUE self) { @@ -164,12 +195,16 @@ ossl_rsa_is_public(VALUE self) GetPKeyRSA(self, pkey); /* - * SURPRISE! :-)) - * Every key is public at the same time! + * This method should check for n and e. BUG. */ return Qtrue; } +/* + * call-seq: + * rsa.private? -> true | false + * + */ static VALUE ossl_rsa_is_private(VALUE self) { @@ -180,6 +215,18 @@ ossl_rsa_is_private(VALUE self) return (RSA_PRIVATE(self, pkey->pkey.rsa)) ? Qtrue : Qfalse; } +/* + * call-seq: + * rsa.to_pem([cipher, pass]) -> aString + * + * === Parameters + * * +cipher+ is a Cipher object. + * * +pass+ is a string. + * + * === Examples + * * rsa.to_pem -> aString + * * rsa.to_pem(cipher, pass) -> aString + */ static VALUE ossl_rsa_export(int argc, VALUE *argv, VALUE self) { @@ -219,6 +266,11 @@ ossl_rsa_export(int argc, VALUE *argv, VALUE self) return str; } +/* + * call-seq: + * rsa.to_der -> aString + * + */ static VALUE ossl_rsa_to_der(VALUE self) { @@ -246,6 +298,11 @@ ossl_rsa_to_der(VALUE self) #define ossl_rsa_buf_size(pkey) (RSA_size((pkey)->pkey.rsa)+16) +/* + * call-seq: + * rsa.public_encrypt(string [, padding]) -> aString + * + */ static VALUE ossl_rsa_public_encrypt(int argc, VALUE *argv, VALUE self) { @@ -267,6 +324,11 @@ ossl_rsa_public_encrypt(int argc, VALUE *argv, VALUE self) return str; } +/* + * call-seq: + * rsa.public_decrypt(string [, padding]) -> aString + * + */ static VALUE ossl_rsa_public_decrypt(int argc, VALUE *argv, VALUE self) { @@ -288,6 +350,11 @@ ossl_rsa_public_decrypt(int argc, VALUE *argv, VALUE self) return str; } +/* + * call-seq: + * rsa.private_encrypt(string [, padding]) -> aString + * + */ static VALUE ossl_rsa_private_encrypt(int argc, VALUE *argv, VALUE self) { @@ -312,6 +379,12 @@ ossl_rsa_private_encrypt(int argc, VALUE *argv, VALUE self) return str; } + +/* + * call-seq: + * rsa.private_decrypt(string [, padding]) -> aString + * + */ static VALUE ossl_rsa_private_decrypt(int argc, VALUE *argv, VALUE self) { @@ -337,6 +410,9 @@ ossl_rsa_private_decrypt(int argc, VALUE *argv, VALUE self) } /* + * call-seq: + * rsa.params -> hash + * * Stores all parameters of key to the hash * INSECURE: PRIVATE INFORMATIONS CAN LEAK OUT!!! * Don't use :-)) (I's up to you) @@ -364,6 +440,9 @@ ossl_rsa_get_params(VALUE self) } /* + * call-seq: + * rsa.to_text -> aString + * * Prints all parameters of key to buffer * INSECURE: PRIVATE INFORMATIONS CAN LEAK OUT!!! * Don't use :-)) (It's up to you) @@ -389,6 +468,9 @@ ossl_rsa_to_text(VALUE self) } /* + * call-seq: + * rsa.public_key -> aRSA + * * Makes new instance RSA PUBLIC_KEY from PRIVATE_KEY */ static VALUE diff --git a/ext/openssl/ossl_rand.c b/ext/openssl/ossl_rand.c index 21af00f30b..ca8c9a5ae9 100644 --- a/ext/openssl/ossl_rand.c +++ b/ext/openssl/ossl_rand.c @@ -36,6 +36,11 @@ ossl_rand_seed(VALUE self, VALUE str) return str; } +/* + * call-seq: + * load_random_file(filename) -> true + * + */ static VALUE ossl_rand_load_file(VALUE self, VALUE filename) { @@ -47,6 +52,11 @@ ossl_rand_load_file(VALUE self, VALUE filename) return Qtrue; } +/* + * call-seq: + * write_random_file(filename) -> true + * + */ static VALUE ossl_rand_write_file(VALUE self, VALUE filename) { @@ -57,6 +67,11 @@ ossl_rand_write_file(VALUE self, VALUE filename) return Qtrue; } +/* + * call-seq: + * random_bytes(length) -> aString + * + */ static VALUE ossl_rand_bytes(VALUE self, VALUE len) { @@ -70,6 +85,11 @@ ossl_rand_bytes(VALUE self, VALUE len) return str; } +/* + * call-seq: + * pseudo_bytes(length) -> aString + * + */ static VALUE ossl_rand_pseudo_bytes(VALUE self, VALUE len) { @@ -83,6 +103,11 @@ ossl_rand_pseudo_bytes(VALUE self, VALUE len) return str; } +/* + * call-seq: + * egd(filename) -> true + * + */ static VALUE ossl_rand_egd(VALUE self, VALUE filename) { @@ -94,6 +119,11 @@ ossl_rand_egd(VALUE self, VALUE filename) return Qtrue; } +/* + * call-seq: + * egd_bytes(filename, length) -> true + * + */ static VALUE ossl_rand_egd_bytes(VALUE self, VALUE filename, VALUE len) { -- cgit v1.2.3