Document RSA, RSA encryption/decryption and PKCS #5 encryption/decryption

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

ChangeLog

@@ -1,3 +1,8 @@
+Sat Dec 11 08:12:48 2010  Eric Hodel  <drbrain@segment7.net>
+
+	* ext/openssl/ossl.c, ext/openssl/ossl_pkey_rsa.c: Document RSA, RSA
+	  encryption/decryption and PKCS #5 encryption/decryption.
+
 Sat Dec 11 06:23:41 2010  Eric Hodel  <drbrain@segment7.net>
 
 	* ext/openssl/ossl_x509name.c: include Comparable to provide #==.

ext/openssl/ossl.c

@@ -469,6 +469,70 @@ ossl_debug_set(VALUE self, VALUE val)
  *   key4_pem = File.read 'private.secure.pem'
  *   key4 = OpenSSL::PKey::RSA.new key4_pem, pass_phrase
  *
+ * == RSA Encryption
+ *
+ * RSA provides ecryption and decryption using the public and private keys.
+ * You can use a variety of padding methods depending upon the intended use of
+ * encrypted data.
+ *
+ * === Encryption
+ *
+ * Documents encrypted with the public key can only be decrypted with the
+ * private key.
+ *
+ *   public_encrypted = key.public_encrypt 'top secret document'
+ *
+ * Documents encrypted with the private key can only be decrypted with the
+ * public key.
+ *
+ *   private_encrypted = key.private_encrypt 'public release document'
+ *
+ * === Decryption
+ *
+ * Use the opposite key type do decrypt the document
+ *
+ *   top_secret = key.public_decrypt public_encrypted
+ *
+ *   public_release = key.private_decrypt private_encrypted
+ *
+ * == PKCS #5 Password-based Encryption
+ *
+ * PKCS #5 is a password-based encryption standard documented at
+ * RFC2898[http://www.ietf.org/rfc/rfc2898.txt].  It allows a short password or
+ * passphrase to be used to create a secure encryption key.
+ *
+ * PKCS #5 uses a Cipher, a pass phrase and a salt to generate an encryption
+ * key.
+ *
+ *   pass_phrase = 'my secure pass phrase goes here'
+ *   salt = '8 octets'
+ *
+ * === Encryption
+ *
+ * First set up the cipher for encryption
+ *
+ *   encrypter = OpenSSL::Cipher::Cipher.new 'AES-128-CBC'
+ *   encrypter.encrypt
+ *   encrypter.pkcs5_keyivgen pass_phrase, salt
+ *
+ * Then pass the data you want to encrypt through
+ *
+ *   encrypted = encrypter.update 'top secret document'
+ *   encrypted << encrypter.final
+ *
+ * === Decryption
+ *
+ * Use a new Cipher instance set up for decryption
+ *
+ *   decrypter = OpenSSL::Cipher::Cipher.new 'AES-128-CBC'
+ *   decrypter.decrypt
+ *   decrypter.pkcs5_keyivgen pass_phrase, salt
+ *
+ * Then pass the data you want to decrypt through
+ *
+ *   plain = decrypter.update encrypted
+ *   plain << decrypter.final
+ *
  * == X509 Certificates
  *
  * === Creating a Certificate
@@ -538,7 +602,7 @@ ossl_debug_set(VALUE self, VALUE val)
  *
  *   ca_key = OpenSSL::PKey::RSA.new 2048
  *
- *   cipher = OpenSSL::Cipher::AES.new 128, :CBC
+ *   cipher = OpenSSL::Cipher::Cipher.new 'AES-128-CBC'
  *
  *   open 'ca_key.pem', 'w', 0400 do |io|
  *     io.write key.export(cipher, pass_phrase)

ext/openssl/ossl_pkey_rsa.c

@@ -85,13 +85,13 @@ rsa_generate(int size, int exp)
 }
 
 /*
- *  call-seq:
+ * call-seq:
- *     RSA.generate(size [, exponent]) -> rsa
+ *   RSA.generate(size)           => RSA instance
- *
+ *   RSA.generate(size, exponent) => RSA instance
- *  === 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.
  *
+ * Generates an RSA keypair.  +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)
@@ -115,18 +115,24 @@ ossl_rsa_s_generate(int argc, VALUE *argv, VALUE klass)
 }
 
 /*
- *  call-seq:
+ * call-seq:
- *     RSA.new([size | encoded_key] [, pass]) -> rsa
+ *   RSA.new(key_size)                 => RSA instance
+ *   RSA.new(encoded_key)              => RSA instance
+ *   RSA.new(encoded_key, pass_phrase) => RSA instance
  *
- *  === Parameters
+ * Generates or loads an RSA keypair.  If an integer +key_size+ is given it
- *  * +size+ is an integer representing the desired key size.
+ * represents the desired key size.  Keys less than 1024 bits should be
- *  * +encoded_key+ is a string containing PEM or DER encoded key.
+ * considered insecure.
- *  * +pass+ is an optional string with the password to decrypt the encoded key.
  *
- *  === Examples
+ * A key can instead be loaded from an +encoded_key+ which must be PEM or DER
- *  * RSA.new(2048) -> rsa
+ * encoded.  A +pass_phrase+ can be used to decrypt the key.  If none is given
- *  * RSA.new(File.read("rsa.pem")) -> rsa
+ * OpenSSL will prompt for the pass phrase.
- *  * RSA.new(File.read("rsa.pem"), "mypassword") -> rsa
+ *
+ * = Examples
+ *
+ *   OpenSSL::PKey::RSA.new 2048
+ *   OpenSSL::PKey::RSA.new File.read 'rsa.pem'
+ *   OpenSSL::PKey::RSA.new File.read('rsa.pem'), 'my pass phrase'
  */
 static VALUE
 ossl_rsa_initialize(int argc, VALUE *argv, VALUE self)
@@ -182,11 +188,11 @@ ossl_rsa_initialize(int argc, VALUE *argv, VALUE self)
 }
 
 /*
- *  call-seq:
+ * call-seq:
- *     rsa.public? -> true
+ *   rsa.public? => true
- *
- *  The return value is always true since every private key is also a public key.
  *
+ * The return value is always true since every private key is also a public
+ * key.
  */
 static VALUE
 ossl_rsa_is_public(VALUE self)
@@ -201,9 +207,10 @@ ossl_rsa_is_public(VALUE self)
 }
 
 /*
- *  call-seq:
+ * call-seq:
- *     rsa.private? -> true | false
+ *   rsa.private? => true | false
  *
+ * Does this keypair contain a private key?
  */
 static VALUE
 ossl_rsa_is_private(VALUE self)
@@ -216,16 +223,13 @@ ossl_rsa_is_private(VALUE self)
 }
 
 /*
- *  call-seq:
+ * call-seq:
- *     rsa.to_pem([cipher, pass]) -> aString
+ *   rsa.to_pem                      => PEM-format String
+ *   rsa.to_pem(cipher, pass_phrase) => PEM-format String
  *
- *  === Parameters
+ * Outputs this keypair in PEM encoding.  If +cipher+ and +pass_phrase+ are
- *  * +cipher+ is a Cipher object.
+ * given they will be used to encrypt the key.  +cipher+ must be an
- *  * +pass+ is a string.
+ * OpenSSL::Cipher::Cipher instance.
- *
- *  === Examples
- *  * rsa.to_pem -> aString
- *  * rsa.to_pem(cipher, pass) -> aString
  */
 static VALUE
 ossl_rsa_export(int argc, VALUE *argv, VALUE self)
@@ -267,9 +271,10 @@ ossl_rsa_export(int argc, VALUE *argv, VALUE self)
 }
 
 /*
- *  call-seq:
+ * call-seq:
- *     rsa.to_der -> aString
+ *   rsa.to_der => DER-format String
  *
+ * Outputs this keypair in DER encoding.
  */
 static VALUE
 ossl_rsa_to_der(VALUE self)
@@ -299,9 +304,12 @@ ossl_rsa_to_der(VALUE self)
 #define ossl_rsa_buf_size(pkey) (RSA_size((pkey)->pkey.rsa)+16)
 
 /*
- *  call-seq:
+ * call-seq:
- *     rsa.public_encrypt(string [, padding]) -> aString
+ *   rsa.public_encrypt(string)          => String
+ *   rsa.public_encrypt(string, padding) => String
  *
+ * Encrypt +string+ with the public key.  +padding+ defaults to PKCS1_PADDING.
+ * The encrypted string output can be decrypted using #private_decrypt.
  */
 static VALUE
 ossl_rsa_public_encrypt(int argc, VALUE *argv, VALUE self)
@@ -325,9 +333,12 @@ ossl_rsa_public_encrypt(int argc, VALUE *argv, VALUE self)
 }
 
 /*
- *  call-seq:
+ * call-seq:
- *     rsa.public_decrypt(string [, padding]) -> aString
+ *   rsa.public_decrypt(string)          => String
+ *   rsa.public_decrypt(string, padding) => String
  *
+ * Decrypt +string+, which has been encrypted with the private key, with the
+ * public key.  +padding+ defaults to PKCS1_PADDING.
  */
 static VALUE
 ossl_rsa_public_decrypt(int argc, VALUE *argv, VALUE self)
@@ -351,9 +362,12 @@ ossl_rsa_public_decrypt(int argc, VALUE *argv, VALUE self)
 }
 
 /*
- *  call-seq:
+ * call-seq:
- *     rsa.private_encrypt(string [, padding]) -> aString
+ *   rsa.private_encrypt(string)          => String
+ *   rsa.private_encrypt(string, padding) => String
  *
+ * Encrypt +string+ with the private key.  +padding+ defaults to PKCS1_PADDING.
+ * The encrypted string output can be decrypted using #public_decrypt.
  */
 static VALUE
 ossl_rsa_private_encrypt(int argc, VALUE *argv, VALUE self)
@@ -379,11 +393,13 @@ ossl_rsa_private_encrypt(int argc, VALUE *argv, VALUE self)
     return str;
 }
 
-
 /*
- *  call-seq:
+ * call-seq:
- *     rsa.private_decrypt(string [, padding]) -> aString
+ *   rsa.private_decrypt(string)          => String
+ *   rsa.private_decrypt(string, padding) => String
  *
+ * Decrypt +string+, which has been encrypted with the public key, with the
+ * private key.  +padding+ defaults to PKCS1_PADDING.
  */
 static VALUE
 ossl_rsa_private_decrypt(int argc, VALUE *argv, VALUE self)
@@ -410,12 +426,15 @@ ossl_rsa_private_decrypt(int argc, VALUE *argv, VALUE self)
 }
 
 /*
- *  call-seq:
+ * call-seq:
- *     rsa.params -> hash
+ *   rsa.params => hash
  *
- * Stores all parameters of key to the hash
+ * THIS METHOD IS INSECURE, PRIVATE INFORMATION CAN LEAK OUT!!!
- * INSECURE: PRIVATE INFORMATIONS CAN LEAK OUT!!!
+ *
- * Don't use :-)) (I's up to you)
+ * Stores all parameters of key to the hash.  The hash has keys 'n', 'e', 'd',
+ * 'p', 'q', 'dmp1', 'dmq1', 'iqmp'.
+ *
+ * Don't use :-)) (It's up to you)
  */
 static VALUE
 ossl_rsa_get_params(VALUE self)
@@ -440,11 +459,13 @@ ossl_rsa_get_params(VALUE self)
 }
 
 /*
- *  call-seq:
+ * call-seq:
- *     rsa.to_text -> aString
+ *   rsa.to_text => String
+ *
+ * THIS METHOD IS INSECURE, PRIVATE INFORMATION CAN LEAK OUT!!!
+ *
+ * Dumps all parameters of a keypair to a String
  *
- * Prints all parameters of key to buffer
- * INSECURE: PRIVATE INFORMATIONS CAN LEAK OUT!!!
  * Don't use :-)) (It's up to you)
  */
 static VALUE
@@ -468,10 +489,10 @@ ossl_rsa_to_text(VALUE self)
 }
 
 /*
- *  call-seq:
+ * call-seq:
- *     rsa.public_key -> aRSA
+ *    rsa.public_key -> RSA
  *
- * Makes new instance RSA PUBLIC_KEY from PRIVATE_KEY
+ * Makes new RSA instance containing the public key from the private key.
  */
 static VALUE
 ossl_rsa_to_public_key(VALUE self)