Ruby  2.0.0p598(2014-11-13revision48408)
ossl_pkcs5.c
Go to the documentation of this file.
1 /*
2  * $Id$
3  * Copyright (C) 2007 Technorama Ltd. <oss-ruby@technorama.net>
4  */
5 #include "ossl.h"
6 
9 
10 #ifdef HAVE_PKCS5_PBKDF2_HMAC
11 /*
12  * call-seq:
13  * PKCS5.pbkdf2_hmac(pass, salt, iter, keylen, digest) => string
14  *
15  * === Parameters
16  * * +pass+ - string
17  * * +salt+ - string - should be at least 8 bytes long.
18  * * +iter+ - integer - should be greater than 1000. 20000 is better.
19  * * +keylen+ - integer
20  * * +digest+ - a string or OpenSSL::Digest object.
21  *
22  * Available in OpenSSL 0.9.4.
23  *
24  * Digests other than SHA1 may not be supported by other cryptography libraries.
25  */
26 static VALUE
28 {
29  VALUE str;
30  const EVP_MD *md;
31  int len = NUM2INT(keylen);
32 
33  StringValue(pass);
34  StringValue(salt);
35  md = GetDigestPtr(digest);
36 
37  str = rb_str_new(0, len);
38 
39  if (PKCS5_PBKDF2_HMAC(RSTRING_PTR(pass), RSTRING_LENINT(pass),
40  (unsigned char *)RSTRING_PTR(salt), RSTRING_LENINT(salt),
41  NUM2INT(iter), md, len,
42  (unsigned char *)RSTRING_PTR(str)) != 1)
43  ossl_raise(ePKCS5, "PKCS5_PBKDF2_HMAC");
44 
45  return str;
46 }
47 #else
48 #define ossl_pkcs5_pbkdf2_hmac rb_f_notimplement
49 #endif
50 
51 
52 #ifdef HAVE_PKCS5_PBKDF2_HMAC_SHA1
53 /*
54  * call-seq:
55  * PKCS5.pbkdf2_hmac_sha1(pass, salt, iter, keylen) => string
56  *
57  * === Parameters
58  * * +pass+ - string
59  * * +salt+ - string - should be at least 8 bytes long.
60  * * +iter+ - integer - should be greater than 1000. 20000 is better.
61  * * +keylen+ - integer
62  *
63  * This method is available in almost any version of OpenSSL.
64  *
65  * Conforms to rfc2898.
66  */
67 static VALUE
69 {
70  VALUE str;
71  int len = NUM2INT(keylen);
72 
73  StringValue(pass);
74  StringValue(salt);
75 
76  str = rb_str_new(0, len);
77 
78  if (PKCS5_PBKDF2_HMAC_SHA1(RSTRING_PTR(pass), RSTRING_LENINT(pass),
79  (const unsigned char *)RSTRING_PTR(salt), RSTRING_LENINT(salt), NUM2INT(iter),
80  len, (unsigned char *)RSTRING_PTR(str)) != 1)
81  ossl_raise(ePKCS5, "PKCS5_PBKDF2_HMAC_SHA1");
82 
83  return str;
84 }
85 #else
86 #define ossl_pkcs5_pbkdf2_hmac_sha1 rb_f_notimplement
87 #endif
88 
89 void
91 {
92  /*
93  * Password-based Encryption
94  *
95  */
96 
97  #if 0
98  mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
99  #endif
100 
101  /* Document-class: OpenSSL::PKCS5
102  *
103  * Provides password-based encryption functionality based on PKCS#5.
104  * Typically used for securely deriving arbitrary length symmetric keys
105  * to be used with an OpenSSL::Cipher from passwords. Another use case
106  * is for storing passwords: Due to the ability to tweak the effort of
107  * computation by increasing the iteration count, computation can be
108  * slowed down artificially in order to render possible attacks infeasible.
109  *
110  * PKCS5 offers support for PBKDF2 with an OpenSSL::Digest::SHA1-based
111  * HMAC, or an arbitrary Digest if the underlying version of OpenSSL
112  * already supports it (>= 0.9.4).
113  *
114  * === Parameters
115  * ==== Password
116  * Typically an arbitrary String that represents the password to be used
117  * for deriving a key.
118  * ==== Salt
119  * Prevents attacks based on dictionaries of common passwords. It is a
120  * public value that can be safely stored along with the password (e.g.
121  * if PBKDF2 is used for password storage). For maximum security, a fresh,
122  * random salt should be generated for each stored password. According
123  * to PKCS#5, a salt should be at least 8 bytes long.
124  * ==== Iteration Count
125  * Allows to tweak the length that the actual computation will take. The
126  * larger the iteration count, the longer it will take.
127  * ==== Key Length
128  * Specifies the length in bytes of the output that will be generated.
129  * Typically, the key length should be larger than or equal to the output
130  * length of the underlying digest function, otherwise an attacker could
131  * simply try to brute-force the key. According to PKCS#5, security is
132  * limited by the output length of the underlying digest function, i.e.
133  * security is not improved if a key length strictly larger than the
134  * digest output length is chosen. Therefore, when using PKCS5 for
135  * password storage, it suffices to store values equal to the digest
136  * output length, nothing is gained by storing larger values.
137  *
138  * == Examples
139  * === Generating a 128 bit key for a Cipher (e.g. AES)
140  * pass = "secret"
141  * salt = OpenSSL::Random.random_bytes(16)
142  * iter = 20000
143  * key_len = 16
144  * key = OpenSSL::PKCS5.pbkdf2_hmac_sha1(pass, salt, iter, key_len)
145  *
146  * === Storing Passwords
147  * pass = "secret"
148  * salt = OpenSSL::Random.random_bytes(16) #store this with the generated value
149  * iter = 20000
150  * digest = OpenSSL::Digest::SHA256.new
151  * len = digest.digest_length
152  * #the final value to be stored
153  * value = OpenSSL::PKCS5.pbkdf2_hmac(pass, salt, iter, len, digest)
154  *
155  * === Important Note on Checking Passwords
156  * When comparing passwords provided by the user with previously stored
157  * values, a common mistake made is comparing the two values using "==".
158  * Typically, "==" short-circuits on evaluation, and is therefore
159  * vulnerable to timing attacks. The proper way is to use a method that
160  * always takes the same amount of time when comparing two values, thus
161  * not leaking any information to potential attackers. To compare two
162  * values, the following could be used:
163  * def eql_time_cmp(a, b)
164  * unless a.length == b.length
165  * return false
166  * end
167  * cmp = b.bytes.to_a
168  * result = 0
169  * a.bytes.each_with_index {|c,i|
170  * result |= c ^ cmp[i]
171  * }
172  * result == 0
173  * end
174  * Please note that the premature return in case of differing lengths
175  * typically does not leak valuable information - when using PKCS#5, the
176  * length of the values to be compared is of fixed size.
177  */
178 
179  mPKCS5 = rb_define_module_under(mOSSL, "PKCS5");
180  /* Document-class: OpenSSL::PKCS5::PKCS5Error
181  *
182  * Generic Exception class that is raised if an error occurs during a
183  * computation.
184  */
185  ePKCS5 = rb_define_class_under(mPKCS5, "PKCS5Error", eOSSLError);
186 
189 }
long keylen
Definition: tkutil.c:1427
VALUE mOSSL
Definition: ossl.c:259
#define RSTRING_PTR(str)
VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super)
Defines a class under the namespace of outer.
Definition: class.c:549
#define ossl_pkcs5_pbkdf2_hmac
Definition: ossl_pkcs5.c:48
void Init_ossl_pkcs5()
Definition: ossl_pkcs5.c:90
static VALUE char * str
Definition: tcltklib.c:3546
const EVP_MD * GetDigestPtr(VALUE obj)
Definition: ossl_digest.c:36
VALUE eOSSLError
Definition: ossl.c:264
void rb_define_module_function(VALUE module, const char *name, VALUE(*func)(ANYARGS), int argc)
Defines a module function for module.
Definition: class.c:1516
#define StringValue(v)
VALUE ePKCS5
Definition: ossl_pkcs5.c:8
VALUE mPKCS5
Definition: ossl_pkcs5.c:7
VALUE rb_define_module_under(VALUE outer, const char *name)
Definition: class.c:641
void ossl_raise(VALUE exc, const char *fmt,...)
Definition: ossl.c:333
#define RSTRING_LENINT(str)
VALUE rb_str_new(const char *, long)
Definition: string.c:425
#define NUM2INT(x)
unsigned long VALUE
Definition: ripper.y:104
long salt
Definition: crypt.c:507
VALUE rb_define_module(const char *name)
Definition: class.c:621
#define ossl_pkcs5_pbkdf2_hmac_sha1
Definition: ossl_pkcs5.c:86
size_t len
Definition: tcltklib.c:3567