10000 Document RSA, RSA encryption/decryption and PKCS #5 encryption/decryp… · smartinez87/ruby@6c7608c · GitHub
[go: up one dir, main page]
Skip to content

Commit 6c7608c

Browse files
drbraindrbrain
committed
Document RSA, RSA encryption/decryption and PKCS ruby#5 encryption/decryption
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@30174 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
1 parent 62e2f90 commit 6c7608c

File tree

3 files changed

+145
-55
lines changed

3 files changed

+145
-55
lines changed

‎ChangeLog

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
Sat Dec 11 08:12:48 2010 Eric Hodel <drbrain@segment7.net>
2+
3+
* ext/openssl/ossl.c, ext/openssl/ossl_pkey_rsa.c: Document RSA, RSA
4+
encryption/decryption and PKCS #5 encryption/decryption.
5+
16
Sat Dec 11 06:23:41 2010 Eric Hodel <drbrain@segment7.net>
27

38
* ext/openssl/ossl_x509name.c: include Comparable to provide #==.

‎ext/openssl/ossl.c

Lines changed: 65 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -469,6 +469,70 @@ ossl_debug_set(VALUE self, VALUE val)
469469
* key4_pem = File.read 'private.secure.pem'
470470
* key4 = OpenSSL::PKey::RSA.new key4_pem, pass_phrase
471471
*
472+
* == RSA Encryption
473+
*
474+
* RSA provides ecryption and decryption using the public and private keys.
475+
* You can use a variety of padding methods depending upon the intended use of
476+
* encrypted data.
477+
*
478+
* === Encryption
479+
*
480+
* Documents encrypted with the public key can only be decrypted with the
481+
* private key.
482+
*
483+
* public_encrypted = key.public_encrypt 'top secret document'
484+
*
485+
* Documents encrypted with the private key can only be decrypted with the
486+
* public key.
487+
*
488+
* private_encrypted = key.private_encrypt 'public release document'
489+
*
490+
* === Decryption
491+
*
492+
* Use the opposite key type do decrypt the document
493+
*
494+
* top_secret = key.public_decrypt public_encrypted
495+
*
496+
* public_release = key.private_decrypt private_encrypted
497+
*
498+
* == PKCS #5 Password-based Encryption
499+
*
500+
* PKCS #5 is a password-based encryption standard documented at
501+
* RFC2898[http://www.ietf.org/rfc/rfc2898.txt]. It allows a short password or
502+
* passphrase to be used to create a secure encryption key.
503+
*
504+
* PKCS #5 uses a Cipher, a pass phrase and a salt to generate an encryption
505+
* key.
506+
*
507+
* pass_phrase = 'my secure pass phrase goes here'
508+
* salt = '8 octets'
509+
*
510+
* === Encryption
511+
*
512+
* First set up the cipher for encryption
< D7AE code>513+
*
514+
* encrypter = OpenSSL::Cipher::Cipher.new 'AES-128-CBC'
515+
* encrypter.encrypt
516+
* encrypter.pkcs5_keyivgen pass_phrase, salt
517+
*
518+
* Then pass the data you want to encrypt through
519+
*
520+
* encrypted = encrypter.update 'top secret document'
521+
* encrypted << encrypter.final
522+
*
523+
* === Decryption
524+
*
525+
* Use a new Cipher instance set up for decryption
526+
*
527+
* decrypter = OpenSSL::Cipher::Cipher.new 'AES-128-CBC'
528+
* decrypter.decrypt
529+
* decrypter.pkcs5_keyivgen pass_phrase, salt
530+
*
531+
* Then pass the data you want to decrypt through
532+
*
533+
* plain = decrypter.update encrypted
534+
* plain << decrypter.final
535+
*
472536
* == X509 Certificates
473537
*
474538
* === Creating a Certificate
@@ -538,7 +602,7 @@ ossl_debug_set(VALUE self, VALUE val)
538602
*
539603
* ca_key = OpenSSL::PKey::RSA.new 2048
540604
*
541-
* cipher = OpenSSL::Cipher::AES.new 128, :CBC
605+
* cipher = OpenSSL::Cipher::Cipher.new 'AES-128-CBC'
542606
*
543607
* open 'ca_key.pem', 'w', 0400 do |io|
544608
* io.write key.export(cipher, pass_phrase)

‎ext/openssl/ossl_pkey_rsa.c

Lines changed: 75 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -85,13 +85,13 @@ rsa_generate(int size, int exp)
8585
}
8686

8787
/*
88-
* call-seq:
89-
* RSA.generate(size [, exponent]) -> rsa
90-
*
91-
* === Parameters
92-
* * +size+ is an integer representing the desired key size. Keys smaller than 1024 should be considered insecure.
93-
* * +exponent+ is an odd number normally 3, 17, or 65537.
88+
* call-seq:
89+
* RSA.generate(size) => RSA instance
90+
* RSA.generate(size, exponent) => RSA instance
9491
*
92+
* Generates an RSA keypair. +size+ is an integer representing the desired key
93+
* size. Keys smaller than 1024 should be considered insecure. +exponent+ is
94+
* an odd number normally 3, 17, or 65537.
9595
*/
9696
static VALUE
9797
ossl_rsa_s_generate(int argc, VALUE *argv, VALUE klass)
@@ -115,18 +115,24 @@ ossl_rsa_s_generate(int argc, VALUE *argv, VALUE klass)
115115
}
116116

117117
/*
118-
* call-seq:
119-
* RSA.new([size | encoded_key] [, pass]) -> rsa
118+
* call-seq:
119+
* RSA.new(key_size) => RSA instance
120+
* RSA.new(encoded_key) => RSA instance
121+
* RSA.new(encoded_key, pass_phrase) => RSA instance
122+
*
123+
* Generates or loads an RSA keypair. If an integer +key_size+ is given it
124+
* represents the desired key size. Keys less than 1024 bits should be
125+
* considered insecure.
126+
*
127+
* A key can instead be loaded from an +encoded_key+ which must be PEM or DER
128+
* encoded. A +pass_phrase+ can be used to decrypt the key. If none is given
129+
* OpenSSL will prompt for the pass phrase.
120130
*
121-
* === Parameters
122-
* * +size+ is an integer representing the desired key size.
123-
* * +encoded_key+ is a string containing PEM or DER encoded key.
124-
* * +pass+ is an optional string with the password to decrypt the encoded key.
131+
* = Examples
125132
*
126-
* === Examples
127-
* * RSA.new(2048) -> rsa
128-
* * RSA.new(File.read("rsa.pem")) -> rsa
129-
* * RSA.new(File.read("rsa.pem"), "mypassword") -> rsa
133+
* OpenSSL::PKey::RSA.new 2048
134+
* OpenSSL::PKey::RSA.new File.read 'rsa.pem'
135+
* OpenSSL::PKey::RSA.new File.read('rsa.pem'), 'my pass phrase'
130136
*/
131137
static VALUE
132138
ossl_rsa_initialize(int argc, VALUE *argv, VALUE self)
@@ -182,11 +188,11 @@ ossl_rsa_initialize(int argc, VALUE *argv, VALUE self)
182188
}
183189

184190
/*
185-
* call-seq:
186-
* rsa.public? -> true
187-
*
188-
* The return value is always true since every private key is also a public key.
191+
* call-seq:
192+
* rsa.public? => true
189193
*
194+
* The return value is always true since every private key is also a public
195+
* key.
190196
*/
191197
static VALUE
192198
ossl_rsa_is_public(VALUE self)
@@ -201,9 +207,10 @@ ossl_rsa_is_public(VALUE self)
201207
}
202208

203209
/*
204-
* call-seq:
205-
* rsa.private? -> true | false
210+
* call-seq:
211+
* rsa.private? => true | false
206212
*
213+
* Does this keypair contain a private key?
207214
*/
208215
static VALUE
209216
ossl_rsa_is_private(VALUE self)
@@ -216,16 +223,13 @@ ossl_rsa_is_private(VALUE self)
216223
}
217224

218225
/*
219-
* call-seq:
220-
* rsa.to_pem([cipher, pass]) -> aString
221-
*
222-
* === Parameters
223-
* * +cipher+ is a Cipher object.
224-
* * +pass+ is a string.
226+
* call-seq:
227+
* rsa.to_pem => PEM-format String
228+
* rsa.to_pem(cipher, pass_phrase) => PEM-format String
225229
*
226-
* === Examples
227-
* * rsa.to_pem -> aString
228-
* * rsa.to_pem(cipher, pass) -> aString
230+
* Outputs this keypair in PEM encoding. If +cipher+ and +pass_phrase+ are
231+
* given they will be used to encrypt the key. +cipher+ must be an
232+
* OpenSSL::Cipher::Cipher instance.
229233
*/
230234
static VALUE
231235
ossl_rsa_export(int argc, VALUE *argv, VALUE self)
@@ -267,9 +271,10 @@ ossl_rsa_export(int argc, VALUE *argv, VALUE self)
267271
}
268272

269273
/*
270-
* call-seq:
271-
* rsa.to_der -> aString
274+
* call-seq:
275+
* rsa.to_der => DER-format String
272276
*
277+
* Outputs this keypair in DER encoding.
273278
*/
274279
static VALUE
275280
ossl_rsa_to_der(VALUE self)
@@ -299,9 +304,12 @@ ossl_rsa_to_der(VALUE self)
299304
#define ossl_rsa_buf_size(pkey) (RSA_size((pkey)->pkey.rsa)+16)
300305

301306
/*
302-
* call-seq:
303-
* rsa.public_encrypt(string [, padding]) -> aString
307+
* call-seq:
308+
* rsa.public_encrypt(string) => String
309+
* rsa.public_encrypt(string, padding) => String
304310
*
311+
* Encrypt +string+ with the public key. +padding+ defaults to PKCS1_PADDING.
312+
* The encrypted string output can be decrypted using #private_decrypt.
305313
*/
306314
static VALUE
307315
ossl_rsa_public_encrypt(int argc, VALUE *argv, VALUE self)
@@ -325,9 +333,12 @@ ossl_rsa_public_encrypt(int argc, VALUE *argv, VALUE self)
325333
}
326334

327335
/*
328-
* call-seq:
329-
* rsa.public_decrypt(string [, padding]) -> aString
336+
* call-seq:
337+
* rsa.public_decrypt(string) => String
338+
* rsa.public_decrypt(string, padding) => String
330339
*
340+
* Decrypt +string+, which has been encrypted with the private key, with the
341+
* public key. +padding+ defaults to PKCS1_PADDING.
331342
*/
332343
static VALUE
333344
ossl_rsa_public_decrypt(int argc, VALUE *argv, VALUE self)
@@ -351,9 +362,12 @@ ossl_rsa_public_decrypt(int argc, VALUE *argv, VALUE self)
351362
}
352363

353364
/*
354-
* call-seq:
355-
* rsa.private_encrypt(string [, padding]) -> aString
365+
* call-seq:
366+
* rsa.private_encrypt(string) => String
367+
* rsa.private_encrypt(string, padding) => String
356368
*
369+
* Encrypt +string+ with the private key. +padding+ defaults to PKCS1_PADDING.
370+
* The encrypted string output can be decrypted using #public_decrypt.
357371
*/
358372
static VALUE
359373
ossl_rsa_private_encrypt(int argc, VALUE *argv, VALUE self)
@@ -379,11 +393,13 @@ ossl_rsa_private_encrypt(int argc, VALUE *argv, VALUE self)
379393
return str;
380394
}
381395

382-
383396
/*
384-
* call-seq:
385-
* rsa.private_decrypt(string [, padding]) -> aString
397+
* call-seq:
398+
* rsa.private_decrypt(string) => String
399+
* rsa.private_decrypt(string, padding) => String
386400
*
401+
* Decrypt +string+, which has been encrypted with the public key, with the
402+
* private key. +padding+ defaults to PKCS1_PADDING.
387403
*/
388404
static VALUE
389405
ossl_rsa_private_decrypt(int argc, VALUE *argv, VALUE self)
@@ -410,12 +426,15 @@ ossl_rsa_private_decrypt(int argc, VALUE *argv, VALUE self)
410426
}
411427

412428
/*
413-
* call-seq:
414-
* rsa.params -> hash
429+
* call-seq:
430+
* rsa.params => hash
415431
*
416-
* Stores all parameters of key to the hash
417-
* INSECURE: PRIVATE INFORMATIONS CAN LEAK OUT!!!
418-
* Don't use :-)) (I's up to you)
432+
* THIS METHOD IS INSECURE, PRIVATE INFORMATION CAN LEAK OUT!!!
433+
*
434+
* Stores all parameters of key to the hash. The hash has keys 'n', 'e', 'd',
435+
* 'p', 'q', 'dmp1', 'dmq1', 'iqmp'.
436+
*
437+
* Don't use :-)) (It's up to you)
419438
*/
420439
static VALUE
421440
ossl_rsa_get_params(VALUE self)
@@ -440,11 +459,13 @@ ossl_rsa_get_params(VALUE self)
440459
}
441460

442461
/*
443-
* call-seq:
444-
* rsa.to_text -> aString
462+
* call-seq:
463+
* rsa.to_text => String
464+
*
465+
* THIS METHOD IS INSECURE, PRIVATE INFORMATION CAN LEAK OUT!!!
466+
*
467+
* Dumps all parameters of a keypair to a String
445468
*
446-
* Prints all parameters of key to buffer
447-
* INSECURE: PRIVATE INFORMATIONS CAN LEAK OUT!!!
448469
* Don't use :-)) (It's up to you)
449470
*/
450471
static VALUE
@@ -468,10 +489,10 @@ ossl_rsa_to_text(VALUE self)
468489
}
469490

470491
/*
471-
* call-seq:
472-
* rsa.public_key -> aRSA
492+
* call-seq:
493+
* rsa.public_key -> RSA
473494
*
474-
* Makes new instance RSA PUBLIC_KEY from PRIVATE_KEY
495+
* Makes new RSA instance containing the public key from the private key.
475496
*/
476497
static VALUE
477498
ossl_rsa_to_public_key(VALUE self)

0 commit comments

Comments
 (0)
0