docs/index.html in pwned-1.2.1 vs docs/index.html in pwned-2.0.0

- old
+ new

@@ -4,11 +4,11 @@ <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title> File: README - &mdash; Documentation by YARD 0.9.12 + &mdash; Documentation by YARD 0.9.20 </title> <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" /> @@ -72,10 +72,37 @@ src="https://inch-ci.org/github/philnash/pwned.svg?branch=master"></a></p> <p><a href="https://philnash.github.io/pwned/">API docs</a> | <a href="https://github.com/philnash/pwned">GitHub repo</a></p> +<h2 id="label-Table+of+Contents">Table of Contents</h2> +<ul><li> +<p><a href="#about">About</a></p> +</li><li> +<p><a href="#installation">Installation</a></p> +</li><li> +<p><a href="#usage">Usage</a></p> +</li><li> +<p><a href="#plain-ruby">Plain Ruby</a></p> +</li><li> +<p><a href="#activerecord-validator">Rails (ActiveRecord)</a></p> +</li><li> +<p><a href="#devise">Devise</a></p> +</li><li> +<p><a href="#command-line">Command line</a></p> +</li><li> +<p><a href="#how-pwned-is-pi">How Pwned is Pi?</a></p> +</li><li> +<p><a href="#development">Development</a></p> +</li><li> +<p><a href="#contributing">Contributing</a></p> +</li><li> +<p><a href="#license">License</a></p> +</li><li> +<p><a href="#code-of-conduct">Code of Conduct</a></p> +</li></ul> + <h2 id="label-About">About</h2> <p>Troy Hunt&#39;s <a href="https://haveibeenpwned.com/API/v2#PwnedPasswords">Pwned Passwords API V2</a> allows you to check if a password has been found in any of the huge @@ -91,10 +118,15 @@ href="https://haveibeenpwned.com/">Have I been pwned?</a>. Before using the API, please check <a href="https://haveibeenpwned.com/API/v2#AcceptableUse">the acceptable uses and license of the API</a>.</p> +<p>Here is a blog post I wrote on <a +href="https://www.twilio.com/blog/2018/03/better-passwords-in-ruby-applications-pwned-passwords-api.html">how +to use this gem in your Ruby applications to make your users’ passwords +better</a>.</p> + <h2 id="label-Installation">Installation</h2> <p>Add this line to your application&#39;s Gemfile:</p> <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>pwned</span><span class='tstring_end'>&#39;</span></span> @@ -110,10 +142,21 @@ <pre class="code ruby"><code class="ruby">$ gem install pwned </code></pre> <h2 id="label-Usage">Usage</h2> +<p>There are a few ways you can use this gem:</p> +<ol><li> +<p><a href="#plain-ruby">Plain Ruby</a></p> +</li><li> +<p><a href="#activerecord-validator">Rails</a></p> +</li><li> +<p><a href="#devise">Rails and Devise</a></p> +</li></ol> + +<h3 id="label-Plain+Ruby">Plain Ruby</h3> + <p>To test a password against the API, instantiate a <code>Pwned::Password</code> object and then ask if it is <code>pwned?</code>.</p> <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_password'>password</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Pwned.html" title="Pwned (module)">Pwned</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Pwned/Password.html" title="Pwned::Password (class)">Password</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="Pwned/Password.html#initialize-instance_method" title="Pwned::Password#initialize (method)">new</a></span></span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>password</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span> @@ -152,16 +195,18 @@ <span class='comment'>#=&gt; 3303003 </span></code></pre> <h4 id="label-Advanced">Advanced</h4> -<p>You can set options and headers to be used with <code>open-uri</code> when -making the request to the API. HTTP headers must be string keys and the <a -href="https://ruby-doc.org/stdlib-2.5.0/libdoc/open-uri/rdoc/OpenURI/OpenRead.html#method-i-open">other -options are available in the OpenURI::OpenRead module</a>.</p> +<p>You can set http request options to be used with +<code>Net::HTTP.start</code> when making the request to the API. These +options are documented in the <a +href="http://ruby-doc.org/stdlib-2.6.3/libdoc/net/http/rdoc/Net/HTTP.html#method-c-start">Net::HTTP.start +documentation</a>. The <code>:headers</code> option defines defines HTTP +headers. These headers must be string keys.</p> -<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_password'>password</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Pwned.html" title="Pwned (module)">Pwned</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Pwned/Password.html" title="Pwned::Password (class)">Password</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="Pwned/Password.html#initialize-instance_method" title="Pwned::Password#initialize (method)">new</a></span></span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>password</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='lbrace'>{</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>User-Agent</span><span class='tstring_end'>&#39;</span></span> <span class='op'>=&gt;</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>Super fun new user agent</span><span class='tstring_end'>&#39;</span></span> <span class='rbrace'>}</span><span class='rparen'>)</span> +<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_password'>password</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Pwned.html" title="Pwned (module)">Pwned</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Pwned/Password.html" title="Pwned::Password (class)">Password</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="Pwned/Password.html#initialize-instance_method" title="Pwned::Password#initialize (method)">new</a></span></span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>password</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>headers:</span> <span class='lbrace'>{</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>User-Agent</span><span class='tstring_end'>&#39;</span></span> <span class='op'>=&gt;</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>Super fun new user agent</span><span class='tstring_end'>&#39;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span> <span class='label'>read_timeout:</span> <span class='int'>10</span><span class='rparen'>)</span> </code></pre> <h3 id="label-ActiveRecord+Validator">ActiveRecord Validator</h3> <p>There is a custom validator available for your ActiveRecord models:</p> @@ -196,11 +241,11 @@ <span class='comment'># The record is marked as valid if the password has been used once in the breached data </span> <span class='id identifier rubyid_validates'>validates</span> <span class='symbol'>:password</span><span class='comma'>,</span> <span class='label'>not_pwned:</span> <span class='lbrace'>{</span> <span class='label'>threshold:</span> <span class='int'>1</span> <span class='rbrace'>}</span> <span class='kw'>end</span> </code></pre> -<h4 id="label-Network+Errors+Handling">Network Errors Handling</h4> +<h4 id="label-Network+Error+Handling">Network Error Handling</h4> <p>By default the record will be treated as valid when we cannot reach the <a href="https://haveibeenpwned.com/">haveibeenpwned.com</a> servers. This can be changed with the <code>:on_error</code> validator parameter:</p> @@ -231,24 +276,109 @@ <h4 id="label-Custom+Request+Options">Custom Request Options</h4> <p>You can configure network requests made from the validator using <code>:request_options</code> (see <a -href="http://ruby-doc.org/stdlib-2.5.0/libdoc/open-uri/rdoc/OpenURI/OpenRead.html#method-i-open">OpenURI::OpenRead#open</a> -for the list of available options, string keys represent custom network -request headers, e.g. <code>&quot;User-Agent&quot;</code>):</p> +href="http://ruby-doc.org/stdlib-2.6.3/libdoc/net/http/rdoc/Net/HTTP.html#method-c-start">Net::HTTP.start</a> +for the list of available options). In addition to these options, HTTP +headers can be specified with the <code>:headers</code> key, e.g. +<code>&quot;User-Agent&quot;</code>):</p> <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_validates'>validates</span> <span class='symbol'>:password</span><span class='comma'>,</span> <span class='label'>not_pwned:</span> <span class='lbrace'>{</span> - <span class='label'>request_options:</span> <span class='lbrace'>{</span> <span class='label'>read_timeout:</span> <span class='int'>5</span><span class='comma'>,</span> <span class='label'>open_timeout:</span> <span class='int'>1</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>User-Agent</span><span class='tstring_end'>&quot;</span></span> <span class='op'>=&gt;</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Super fun user agent</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span> + <span class='label'>request_options:</span> <span class='lbrace'>{</span> <span class='label'>read_timeout:</span> <span class='int'>5</span><span class='comma'>,</span> <span class='label'>open_timeout:</span> <span class='int'>1</span><span class='comma'>,</span> <span class='label'>headers:</span> <span class='lbrace'>{</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>User-Agent</span><span class='tstring_end'>&quot;</span></span> <span class='op'>=&gt;</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Super fun user agent</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span> <span class='rbrace'>}</span> <span class='rbrace'>}</span> </code></pre> -<h2 id="label-TODO">TODO</h2> -<ul><li> -<p>[ ] Devise plugin</p> -</li></ul> +<h3 id="label-Devise">Devise</h3> +<p>If you are using Devise I recommend you use the <a +href="https://github.com/michaelbanfield/devise-pwned_password">devise-pwned_password +extension</a> which is now powered by this gem.</p> + +<h3 id="label-Command+line">Command line</h3> + +<p>The gem provides a command line utility for checking passwords. You can +call it from your terminal application like this:</p> + +<pre class="code ruby"><code class="ruby">$ pwned password +Pwned! +The password has been found in public breaches 3645804 times. +</code></pre> + +<p>If you don&#39;t want the password you are checking to be visible, call:</p> + +<pre class="code ruby"><code class="ruby">$ pwned --secret +</code></pre> + +<p>You will be prompted for the password, but it won&#39;t be displayed.</p> + +<h2 id="label-How+Pwned+is+Pi-3F">How Pwned is Pi?</h2> + +<p><a href="https://github.com/daz">@daz</a> <a +href="https://twitter.com/dazonic/status/1074647842046660609">shared</a> a +fantastic example of using this gem to show how many times the digits of Pi +have been used as passwords and leaked.</p> + +<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>pwned</span><span class='tstring_end'>&#39;</span></span> + +<span class='const'>PI</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>3.14159265358979323846264338327950288419716939937510582097494459230781640628620899862803482534211706798214808651328230664709384460955058223172535940812848111</span><span class='tstring_end'>&#39;</span></span> + +<span class='kw'>for</span> <span class='id identifier rubyid_n'>n</span> <span class='kw'>in</span> <span class='int'>1</span><span class='op'>..</span><span class='int'>40</span> + <span class='id identifier rubyid_password'>password</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Pwned.html" title="Pwned (module)">Pwned</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Pwned/Password.html" title="Pwned::Password (class)">Password</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="Pwned/Password.html#initialize-instance_method" title="Pwned::Password#initialize (method)">new</a></span></span> <span class='const'>PI</span><span class='lbracket'>[</span><span class='int'>0</span><span class='op'>..</span><span class='lparen'>(</span><span class='id identifier rubyid_n'>n</span> <span class='op'>+</span> <span class='int'>1</span><span class='rparen'>)</span><span class='rbracket'>]</span> + <span class='id identifier rubyid_str'>str</span> <span class='op'>=</span> <span class='lbracket'>[</span> <span class='id identifier rubyid_n'>n</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='period'>.</span><span class='id identifier rubyid_rjust'>rjust</span><span class='lparen'>(</span><span class='int'>2</span><span class='rparen'>)</span> <span class='rbracket'>]</span> + <span class='id identifier rubyid_str'>str</span> <span class='op'>&lt;&lt;</span> <span class='lparen'>(</span><span class='id identifier rubyid_password'>password</span><span class='period'>.</span><span class='id identifier rubyid_pwned?'>pwned?</span> <span class='op'>?</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>😑</span><span class='tstring_end'>&#39;</span></span> <span class='op'>:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>πŸ˜ƒ</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> + <span class='id identifier rubyid_str'>str</span> <span class='op'>&lt;&lt;</span> <span class='id identifier rubyid_password'>password</span><span class='period'>.</span><span class='id identifier rubyid_pwned_count'>pwned_count</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='period'>.</span><span class='id identifier rubyid_rjust'>rjust</span><span class='lparen'>(</span><span class='int'>4</span><span class='rparen'>)</span> + <span class='id identifier rubyid_str'>str</span> <span class='op'>&lt;&lt;</span> <span class='id identifier rubyid_password'>password</span><span class='period'>.</span><span class='id identifier rubyid_password'>password</span> + + <span class='id identifier rubyid_puts'>puts</span> <span class='id identifier rubyid_str'>str</span><span class='period'>.</span><span class='id identifier rubyid_join'>join</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'> </span><span class='tstring_end'>&#39;</span></span> +<span class='kw'>end</span> +</code></pre> + +<p>The results may, or may not, surprise you.</p> + +<pre class="code ruby"><code class="ruby">1 😑 16 3.1 + 2 😑 238 3.14 + 3 😑 34 3.141 + 4 😑 1345 3.1415 + 5 😑 2552 3.14159 + 6 😑 791 3.141592 + 7 😑 9582 3.1415926 + 8 😑 1591 3.14159265 + 9 😑 637 3.141592653 +10 😑 873 3.1415926535 +11 😑 137 3.14159265358 +12 😑 103 3.141592653589 +13 😑 65 3.1415926535897 +14 😑 201 3.14159265358979 +15 😑 41 3.141592653589793 +16 😑 57 3.1415926535897932 +17 😑 28 3.14159265358979323 +18 😑 29 3.141592653589793238 +19 😑 1 3.1415926535897932384 +20 😑 7 3.14159265358979323846 +21 😑 5 3.141592653589793238462 +22 😑 2 3.1415926535897932384626 +23 😑 2 3.14159265358979323846264 +24 πŸ˜ƒ 0 3.141592653589793238462643 +25 😑 3 3.1415926535897932384626433 +26 πŸ˜ƒ 0 3.14159265358979323846264338 +27 πŸ˜ƒ 0 3.141592653589793238462643383 +28 πŸ˜ƒ 0 3.1415926535897932384626433832 +29 πŸ˜ƒ 0 3.14159265358979323846264338327 +30 πŸ˜ƒ 0 3.141592653589793238462643383279 +31 πŸ˜ƒ 0 3.1415926535897932384626433832795 +32 πŸ˜ƒ 0 3.14159265358979323846264338327950 +33 πŸ˜ƒ 0 3.141592653589793238462643383279502 +34 πŸ˜ƒ 0 3.1415926535897932384626433832795028 +35 πŸ˜ƒ 0 3.14159265358979323846264338327950288 +36 πŸ˜ƒ 0 3.141592653589793238462643383279502884 +37 πŸ˜ƒ 0 3.1415926535897932384626433832795028841 +38 πŸ˜ƒ 0 3.14159265358979323846264338327950288419 +39 πŸ˜ƒ 0 3.141592653589793238462643383279502884197 +40 πŸ˜ƒ 0 3.1415926535897932384626433832795028841971 +</code></pre> + <h2 id="label-Development">Development</h2> <p>After checking out the repo, run <code>bin/setup</code> to install dependencies. Then, run <code>rake spec</code> to run the tests. You can also run <code>bin/console</code> for an interactive prompt that will allow @@ -282,12 +412,12 @@ href="https://github.com/philnash/pwned/blob/master/CODE_OF_CONDUCT.md">code of conduct</a>.</p> </div></div> <div id="footer"> - Generated on Sat Mar 17 09:15:05 2018 by + Generated on Tue Oct 1 21:19:36 2019 by <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a> - 0.9.12 (ruby-2.5.0). + 0.9.20 (ruby-2.5.5). </div> </div> </body> </html> \ No newline at end of file