File: C:/Ruby27-x64/share/doc/ruby/html/OpenSSL/KDF.html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>module OpenSSL::KDF - RDoc Documentation</title>
<script type="text/javascript">
var rdoc_rel_prefix = "../";
var index_rel_prefix = "../";
</script>
<script src="../js/navigation.js" defer></script>
<script src="../js/search.js" defer></script>
<script src="../js/search_index.js" defer></script>
<script src="../js/searcher.js" defer></script>
<script src="../js/darkfish.js" defer></script>
<link href="../css/fonts.css" rel="stylesheet">
<link href="../css/rdoc.css" rel="stylesheet">
<body id="top" role="document" class="module">
<nav role="navigation">
<div id="project-navigation">
<div id="home-section" role="region" title="Quick navigation" class="nav-section">
<h2>
<a href="../index.html" rel="home">Home</a>
</h2>
<div id="table-of-contents-navigation">
<a href="../table_of_contents.html#pages">Pages</a>
<a href="../table_of_contents.html#classes">Classes</a>
<a href="../table_of_contents.html#methods">Methods</a>
</div>
</div>
<div id="search-section" role="search" class="project-section initially-hidden">
<form action="#" method="get" accept-charset="utf-8">
<div id="search-field-wrapper">
<input id="search-field" role="combobox" aria-label="Search"
aria-autocomplete="list" aria-controls="search-results"
type="text" name="search" placeholder="Search" spellcheck="false"
title="Type to search, Up and Down to navigate, Enter to load">
</div>
<ul id="search-results" aria-label="Search Results"
aria-busy="false" aria-expanded="false"
aria-atomic="false" class="initially-hidden"></ul>
</form>
</div>
</div>
<div class="nav-section">
<h3>Table of Contents</h3>
<ul class="link-list" role="directory">
<li><a href="#module-OpenSSL::KDF-label-Examples">Examples</a>
<li><a href="#module-OpenSSL::KDF-label-Generating+a+128+bit+key+for+a+Cipher+-28e.g.+AES-29">Generating a 128 bit key for a Cipher (e.g. AES)</a>
<li><a href="#module-OpenSSL::KDF-label-Storing+Passwords">Storing Passwords</a>
<li><a href="#module-OpenSSL::KDF-label-Important+Note+on+Checking+Passwords">Important Note on Checking Passwords</a>
</ul>
</div>
<div id="class-metadata">
<!-- Method Quickref -->
<div id="method-list-section" class="nav-section">
<h3>Methods</h3>
<ul class="link-list" role="directory">
<li ><a href="#method-c-hkdf">::hkdf</a>
<li ><a href="#method-c-pbkdf2_hmac">::pbkdf2_hmac</a>
<li ><a href="#method-c-scrypt">::scrypt</a>
</ul>
</div>
</div>
</nav>
<main role="main" aria-labelledby="module-OpenSSL::KDF">
<h1 id="module-OpenSSL::KDF" class="module">
module OpenSSL::KDF
</h1>
<section class="description">
<p>Provides functionality of various KDFs (key derivation function).</p>
<p><a href="KDF.html"><code>KDF</code></a> is typically used for securely deriving arbitrary length symmetric keys to be used with an <a href="Cipher.html"><code>OpenSSL::Cipher</code></a> from passwords. Another use case is for storing passwords: Due to the ability to tweak the effort of computation by increasing the iteration count, computation can be slowed down artificially in order to render possible attacks infeasible.</p>
<p>Currently, <a href="KDF.html"><code>OpenSSL::KDF</code></a> provides implementations for the following KDF:</p>
<ul><li>
<p>PKCS #5 PBKDF2 (Password-Based Key Derivation Function 2) in combination with <a href="HMAC.html"><code>HMAC</code></a></p>
</li><li>
<p>scrypt</p>
</li><li>
<p>HKDF</p>
</li></ul>
<h2 id="module-OpenSSL::KDF-label-Examples">Examples<span><a href="#module-OpenSSL::KDF-label-Examples">¶</a> <a href="#top">↑</a></span></h2>
<h3 id="module-OpenSSL::KDF-label-Generating+a+128+bit+key+for+a+Cipher+-28e.g.+AES-29">Generating a 128 bit key for a <a href="Cipher.html"><code>Cipher</code></a> (e.g. AES)<span><a href="#module-OpenSSL::KDF-label-Generating+a+128+bit+key+for+a+Cipher+-28e.g.+AES-29">¶</a> <a href="#top">↑</a></span></h3>
<pre class="ruby"><span class="ruby-identifier">pass</span> = <span class="ruby-string">"secret"</span>
<span class="ruby-identifier">salt</span> = <span class="ruby-constant">OpenSSL</span><span class="ruby-operator">::</span><span class="ruby-constant">Random</span>.<span class="ruby-identifier">random_bytes</span>(<span class="ruby-value">16</span>)
<span class="ruby-identifier">iter</span> = <span class="ruby-value">20_000</span>
<span class="ruby-identifier">key_len</span> = <span class="ruby-value">16</span>
<span class="ruby-identifier">key</span> = <span class="ruby-constant">OpenSSL</span><span class="ruby-operator">::</span><span class="ruby-constant">KDF</span>.<span class="ruby-identifier">pbkdf2_hmac</span>(<span class="ruby-identifier">pass</span>, <span class="ruby-value">salt:</span> <span class="ruby-identifier">salt</span>, <span class="ruby-value">iterations:</span> <span class="ruby-identifier">iter</span>,
<span class="ruby-value">length:</span> <span class="ruby-identifier">key_len</span>, <span class="ruby-value">hash:</span> <span class="ruby-string">"sha1"</span>)
</pre>
<h3 id="module-OpenSSL::KDF-label-Storing+Passwords">Storing Passwords<span><a href="#module-OpenSSL::KDF-label-Storing+Passwords">¶</a> <a href="#top">↑</a></span></h3>
<pre class="ruby"><span class="ruby-identifier">pass</span> = <span class="ruby-string">"secret"</span>
<span class="ruby-comment"># store this with the generated value</span>
<span class="ruby-identifier">salt</span> = <span class="ruby-constant">OpenSSL</span><span class="ruby-operator">::</span><span class="ruby-constant">Random</span>.<span class="ruby-identifier">random_bytes</span>(<span class="ruby-value">16</span>)
<span class="ruby-identifier">iter</span> = <span class="ruby-value">20_000</span>
<span class="ruby-identifier">hash</span> = <span class="ruby-constant">OpenSSL</span><span class="ruby-operator">::</span><span class="ruby-constant">Digest</span><span class="ruby-operator">::</span><span class="ruby-constant">SHA256</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">len</span> = <span class="ruby-identifier">hash</span>.<span class="ruby-identifier">digest_length</span>
<span class="ruby-comment"># the final value to be stored</span>
<span class="ruby-identifier">value</span> = <span class="ruby-constant">OpenSSL</span><span class="ruby-operator">::</span><span class="ruby-constant">KDF</span>.<span class="ruby-identifier">pbkdf2_hmac</span>(<span class="ruby-identifier">pass</span>, <span class="ruby-value">salt:</span> <span class="ruby-identifier">salt</span>, <span class="ruby-value">iterations:</span> <span class="ruby-identifier">iter</span>,
<span class="ruby-value">length:</span> <span class="ruby-identifier">len</span>, <span class="ruby-value">hash:</span> <span class="ruby-identifier">hash</span>)
</pre>
<h2 id="module-OpenSSL::KDF-label-Important+Note+on+Checking+Passwords">Important Note on Checking Passwords<span><a href="#module-OpenSSL::KDF-label-Important+Note+on+Checking+Passwords">¶</a> <a href="#top">↑</a></span></h2>
<p>When comparing passwords provided by the user with previously stored values, a common mistake made is comparing the two values using “==”. Typically, “==” short-circuits on evaluation, and is therefore vulnerable to timing attacks. The proper way is to use a method that always takes the same amount of time when comparing two values, thus not leaking any information to potential attackers. To compare two values, the following could be used:</p>
<pre class="ruby"><span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">eql_time_cmp</span>(<span class="ruby-identifier">a</span>, <span class="ruby-identifier">b</span>)
<span class="ruby-keyword">unless</span> <span class="ruby-identifier">a</span>.<span class="ruby-identifier">length</span> <span class="ruby-operator">==</span> <span class="ruby-identifier">b</span>.<span class="ruby-identifier">length</span>
<span class="ruby-keyword">return</span> <span class="ruby-keyword">false</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">cmp</span> = <span class="ruby-identifier">b</span>.<span class="ruby-identifier">bytes</span>
<span class="ruby-identifier">result</span> = <span class="ruby-value">0</span>
<span class="ruby-identifier">a</span>.<span class="ruby-identifier">bytes</span>.<span class="ruby-identifier">each_with_index</span> {<span class="ruby-operator">|</span><span class="ruby-identifier">c</span>,<span class="ruby-identifier">i</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">result</span> <span class="ruby-operator">|=</span> <span class="ruby-identifier">c</span> <span class="ruby-operator">^</span> <span class="ruby-identifier">cmp</span>[<span class="ruby-identifier">i</span>]
}
<span class="ruby-identifier">result</span> <span class="ruby-operator">==</span> <span class="ruby-value">0</span>
<span class="ruby-keyword">end</span>
</pre>
<p>Please note that the premature return in case of differing lengths typically does not leak valuable information - when using PBKDF2, the length of the values to be compared is of fixed size.</p>
</section>
<section id="5Buntitled-5D" class="documentation-section">
<section id="public-class-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Class Methods</h3>
</header>
<div id="method-c-hkdf" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
hkdf(ikm, salt:, info:, length:, hash:) → String
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>HMAC-based Extract-and-Expand Key Derivation Function (HKDF) as specified in <a href="https://tools.ietf.org/html/rfc5869">RFC 5869</a>.</p>
<p>New in <a href="../OpenSSL.html"><code>OpenSSL</code></a> 1.1.0.</p>
<h3 id="method-c-hkdf-label-Parameters">Parameters<span><a href="#method-c-hkdf-label-Parameters">¶</a> <a href="#top">↑</a></span></h3>
<dl class="rdoc-list note-list"><dt><em>ikm</em>
<dd>
<p>The input keying material.</p>
</dd><dt><em>salt</em>
<dd>
<p>The salt.</p>
</dd><dt><em>info</em>
<dd>
<p>The context and application specific information.</p>
</dd><dt><em>length</em>
<dd>
<p>The output length in octets. Must be <= <code>255 * HashLen</code>, where HashLen is the length of the hash function output in octets.</p>
</dd><dt><em>hash</em>
<dd>
<p>The hash function.</p>
</dd></dl>
<div class="method-source-code" id="hkdf-source">
<pre>static VALUE
kdf_hkdf(int argc, VALUE *argv, VALUE self)
{
VALUE ikm, salt, info, opts, kwargs[4], str;
static ID kwargs_ids[4];
int saltlen, ikmlen, infolen;
size_t len;
const EVP_MD *md;
EVP_PKEY_CTX *pctx;
if (!kwargs_ids[0]) {
kwargs_ids[0] = rb_intern_const("salt");
kwargs_ids[1] = rb_intern_const("info");
kwargs_ids[2] = rb_intern_const("length");
kwargs_ids[3] = rb_intern_const("hash");
}
rb_scan_args(argc, argv, "1:", &ikm, &opts);
rb_get_kwargs(opts, kwargs_ids, 4, 0, kwargs);
StringValue(ikm);
ikmlen = RSTRING_LENINT(ikm);
salt = StringValue(kwargs[0]);
saltlen = RSTRING_LENINT(salt);
info = StringValue(kwargs[1]);
infolen = RSTRING_LENINT(info);
len = (size_t)NUM2LONG(kwargs[2]);
if (len > LONG_MAX)
rb_raise(rb_eArgError, "length must be non-negative");
md = ossl_evp_get_digestbyname(kwargs[3]);
str = rb_str_new(NULL, (long)len);
pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL);
if (!pctx)
ossl_raise(eKDF, "EVP_PKEY_CTX_new_id");
if (EVP_PKEY_derive_init(pctx) <= 0) {
EVP_PKEY_CTX_free(pctx);
ossl_raise(eKDF, "EVP_PKEY_derive_init");
}
if (EVP_PKEY_CTX_set_hkdf_md(pctx, md) <= 0) {
EVP_PKEY_CTX_free(pctx);
ossl_raise(eKDF, "EVP_PKEY_CTX_set_hkdf_md");
}
if (EVP_PKEY_CTX_set1_hkdf_salt(pctx, (unsigned char *)RSTRING_PTR(salt),
saltlen) <= 0) {
EVP_PKEY_CTX_free(pctx);
ossl_raise(eKDF, "EVP_PKEY_CTX_set_hkdf_salt");
}
if (EVP_PKEY_CTX_set1_hkdf_key(pctx, (unsigned char *)RSTRING_PTR(ikm),
ikmlen) <= 0) {
EVP_PKEY_CTX_free(pctx);
ossl_raise(eKDF, "EVP_PKEY_CTX_set_hkdf_key");
}
if (EVP_PKEY_CTX_add1_hkdf_info(pctx, (unsigned char *)RSTRING_PTR(info),
infolen) <= 0) {
EVP_PKEY_CTX_free(pctx);
ossl_raise(eKDF, "EVP_PKEY_CTX_set_hkdf_info");
}
if (EVP_PKEY_derive(pctx, (unsigned char *)RSTRING_PTR(str), &len) <= 0) {
EVP_PKEY_CTX_free(pctx);
ossl_raise(eKDF, "EVP_PKEY_derive");
}
rb_str_set_len(str, (long)len);
EVP_PKEY_CTX_free(pctx);
return str;
}</pre>
</div>
</div>
</div>
<div id="method-c-pbkdf2_hmac" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
pbkdf2_hmac(pass, salt:, iterations:, length:, hash:) → aString
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>PKCS #5 PBKDF2 (Password-Based Key Derivation Function 2) in combination with <a href="HMAC.html"><code>HMAC</code></a>. Takes <em>pass</em>, <em>salt</em> and <em>iterations</em>, and then derives a key of <em>length</em> bytes.</p>
<p>For more information about PBKDF2, see RFC 2898 Section 5.2 (<a href="https://tools.ietf.org/html/rfc2898#section-5.2">tools.ietf.org/html/rfc2898#section-5.2</a>).</p>
<h3 id="method-c-pbkdf2_hmac-label-Parameters">Parameters<span><a href="#method-c-pbkdf2_hmac-label-Parameters">¶</a> <a href="#top">↑</a></span></h3>
<dl class="rdoc-list note-list"><dt>pass
<dd>
<p>The passphrase.</p>
</dd><dt>salt
<dd>
<p>The salt. Salts prevent attacks based on dictionaries of common passwords and attacks based on rainbow tables. It is a public value that can be safely stored along with the password (e.g. if the derived value is used for password storage).</p>
</dd><dt>iterations
<dd>
<p>The iteration count. This provides the ability to tune the algorithm. It is better to use the highest count possible for the maximum resistance to brute-force attacks.</p>
</dd><dt>length
<dd>
<p>The desired length of the derived key in octets.</p>
</dd><dt>hash
<dd>
<p>The hash algorithm used with <a href="HMAC.html"><code>HMAC</code></a> for the PRF. May be a <a href="../String.html"><code>String</code></a> representing the algorithm name, or an instance of <a href="Digest.html"><code>OpenSSL::Digest</code></a>.</p>
</dd></dl>
<div class="method-source-code" id="pbkdf2_hmac-source">
<pre>static VALUE
kdf_pbkdf2_hmac(int argc, VALUE *argv, VALUE self)
{
VALUE pass, salt, opts, kwargs[4], str;
static ID kwargs_ids[4];
int iters, len;
const EVP_MD *md;
if (!kwargs_ids[0]) {
kwargs_ids[0] = rb_intern_const("salt");
kwargs_ids[1] = rb_intern_const("iterations");
kwargs_ids[2] = rb_intern_const("length");
kwargs_ids[3] = rb_intern_const("hash");
}
rb_scan_args(argc, argv, "1:", &pass, &opts);
rb_get_kwargs(opts, kwargs_ids, 4, 0, kwargs);
StringValue(pass);
salt = StringValue(kwargs[0]);
iters = NUM2INT(kwargs[1]);
len = NUM2INT(kwargs[2]);
md = ossl_evp_get_digestbyname(kwargs[3]);
str = rb_str_new(0, len);
if (!PKCS5_PBKDF2_HMAC(RSTRING_PTR(pass), RSTRING_LENINT(pass),
(unsigned char *)RSTRING_PTR(salt),
RSTRING_LENINT(salt), iters, md, len,
(unsigned char *)RSTRING_PTR(str)))
ossl_raise(eKDF, "PKCS5_PBKDF2_HMAC");
return str;
}</pre>
</div>
</div>
</div>
<div id="method-c-scrypt" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
scrypt(pass, salt:, N:, r:, p:, length:) → aString
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Derives a key from <em>pass</em> using given parameters with the scrypt password-based key derivation function. The result can be used for password storage.</p>
<p>scrypt is designed to be memory-hard and more secure against brute-force attacks using custom hardwares than alternative KDFs such as PBKDF2 or bcrypt.</p>
<p>The keyword arguments <em>N</em>, <em>r</em> and <em>p</em> can be used to tune scrypt. RFC 7914 (published on 2016-08, <a href="https://tools.ietf.org/html/rfc7914#section-2">tools.ietf.org/html/rfc7914#section-2</a>) states that using values r=8 and p=1 appears to yield good results.</p>
<p>See RFC 7914 (<a href="https://tools.ietf.org/html/rfc7914">tools.ietf.org/html/rfc7914</a>) for more information.</p>
<h3 id="method-c-scrypt-label-Parameters">Parameters<span><a href="#method-c-scrypt-label-Parameters">¶</a> <a href="#top">↑</a></span></h3>
<dl class="rdoc-list note-list"><dt>pass
<dd>
<p>Passphrase.</p>
</dd><dt>salt
<dd>
<p>Salt.</p>
</dd><dt>N
<dd>
<p>CPU/memory cost parameter. This must be a power of 2.</p>
</dd><dt>r
<dd>
<p>Block size parameter.</p>
</dd><dt>p
<dd>
<p>Parallelization parameter.</p>
</dd><dt>length
<dd>
<p>Length in octets of the derived key.</p>
</dd></dl>
<h3 id="method-c-scrypt-label-Example">Example<span><a href="#method-c-scrypt-label-Example">¶</a> <a href="#top">↑</a></span></h3>
<pre class="ruby"><span class="ruby-identifier">pass</span> = <span class="ruby-string">"password"</span>
<span class="ruby-identifier">salt</span> = <span class="ruby-constant">SecureRandom</span>.<span class="ruby-identifier">random_bytes</span>(<span class="ruby-value">16</span>)
<span class="ruby-identifier">dk</span> = <span class="ruby-constant">OpenSSL</span><span class="ruby-operator">::</span><span class="ruby-constant">KDF</span>.<span class="ruby-identifier">scrypt</span>(<span class="ruby-identifier">pass</span>, <span class="ruby-value">salt:</span> <span class="ruby-identifier">salt</span>, <span class="ruby-value">N:</span> <span class="ruby-value">2</span><span class="ruby-operator">**</span><span class="ruby-value">14</span>, <span class="ruby-value">r:</span> <span class="ruby-value">8</span>, <span class="ruby-value">p:</span> <span class="ruby-value">1</span>, <span class="ruby-value">length:</span> <span class="ruby-value">32</span>)
<span class="ruby-identifier">p</span> <span class="ruby-identifier">dk</span> <span class="ruby-comment">#=> "\xDA\xE4\xE2...\x7F\xA1\x01T"</span>
</pre>
<div class="method-source-code" id="scrypt-source">
<pre>static VALUE
kdf_scrypt(int argc, VALUE *argv, VALUE self)
{
VALUE pass, salt, opts, kwargs[5], str;
static ID kwargs_ids[5];
size_t len;
uint64_t N, r, p, maxmem;
if (!kwargs_ids[0]) {
kwargs_ids[0] = rb_intern_const("salt");
kwargs_ids[1] = rb_intern_const("N");
kwargs_ids[2] = rb_intern_const("r");
kwargs_ids[3] = rb_intern_const("p");
kwargs_ids[4] = rb_intern_const("length");
}
rb_scan_args(argc, argv, "1:", &pass, &opts);
rb_get_kwargs(opts, kwargs_ids, 5, 0, kwargs);
StringValue(pass);
salt = StringValue(kwargs[0]);
N = NUM2UINT64T(kwargs[1]);
r = NUM2UINT64T(kwargs[2]);
p = NUM2UINT64T(kwargs[3]);
len = NUM2LONG(kwargs[4]);
/*
* OpenSSL uses 32MB by default (if zero is specified), which is too small.
* Let's not limit memory consumption but just let malloc() fail inside
* OpenSSL. The amount is controllable by other parameters.
*/
maxmem = SIZE_MAX;
str = rb_str_new(0, len);
if (!EVP_PBE_scrypt(RSTRING_PTR(pass), RSTRING_LEN(pass),
(unsigned char *)RSTRING_PTR(salt), RSTRING_LEN(salt),
N, r, p, maxmem, (unsigned char *)RSTRING_PTR(str), len))
ossl_raise(eKDF, "EVP_PBE_scrypt");
return str;
}</pre>
</div>
</div>
</div>
</section>
</section>
</main>
<footer id="validator-badges" role="contentinfo">
<p><a href="https://validator.w3.org/check/referer">Validate</a>
<p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.2.1.1.
<p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
</footer>