0.x/reference/derivepassphrase.vault/index.html (50490f6) - derivepassphrase.git

index.html

<!doctype html>
<html lang="en" class="no-js">
  <head>
    
      <meta charset="utf-8">
      <meta name="viewport" content="width=device-width,initial-scale=1">
      
        <meta name="description" content="An almost faithful Python reimplementation of James Coglan's vault.">
      
      
        <meta name="author" content="Marco Ricci">
      
      
        <link rel="canonical" href="https://the13thletter.info/derivepassphrase/0.x/reference/derivepassphrase.vault/">
      
      
        <link rel="prev" href="../derivepassphrase._types/">
      
      
        <link rel="next" href="../../changelog/">
      
      
      <link rel="icon" href="../../assets/images/favicon.png">
      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.5.39">
    
    
      
        <title>Submodule vault - derivepassphrase</title>
      
    
    
      <link rel="stylesheet" href="../../assets/stylesheets/main.8c3ca2c6.min.css">

</a>
    </li>

<li class="md-tabs__item">
        <a href="../../tutorials/basic-setup-passphrase/" class="md-tabs__link">
          
  
    
  
  Tutorials & Examples

</a>
      </li>

<li class="md-tabs__item md-tabs__item--active">
        <a href="../" class="md-tabs__link">
          
  
    
  
  Reference

</a>
      </li>

<li class="md-tabs__item">
      <a href="../../changelog/" class="md-tabs__link">
        
  
    
  
  Changelog

</a>
    </li>

</ul>
  </div>
</nav>
          
        
      
      <main class="md-main" data-md-component="main">
        <div class="md-main__inner md-grid">
          
            
              
              <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
                <div class="md-sidebar__scrollwrap">
                  <div class="md-sidebar__inner">

</a>
    derivepassphrase
  </label>
  
    <div class="md-nav__source">
      <a href="https://github.com/the-13th-letter/derivepassphrase" title="Go to repository" class="md-source" data-md-component="source">
  <div class="md-source__icon md-icon">
    
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81"/></svg>
  </div>
  <div class="md-source__repository">
    the-13th-letter/derivepassphrase
  </div>
</a>
    </div>
  
  <ul class="md-nav__list" data-md-scrollfix>
    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href="../.." class="md-nav__link">
        
  
  <span class="md-ellipsis">
    Overview
  </span>

</a>
    </li>

<li class="md-nav__item md-nav__item--nested">
      
        
        
        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2" >
        
          
          <label class="md-nav__link" for="__nav_2" id="__nav_2_label" tabindex="0">
            
  
  <span class="md-ellipsis">
    Tutorials & Examples
  </span>

<span class="md-nav__icon md-icon"></span>
          </label>
        
        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="false">
          <label class="md-nav__title" for="__nav_2">
            <span class="md-nav__icon md-icon"></span>
            Tutorials & Examples
          </label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
                
  
  
  
  
    <li class="md-nav__item">
      <a href="../../tutorials/basic-setup-passphrase/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    Tutorial: setting up derivepassphrase vault for three accounts, with a master passphrase
  </span>

</a>
    </li>

</ul>
        </nav>
      
    </li>

<li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
      
        
        
        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" checked>
        
          
          
          <div class="md-nav__link md-nav__container">
            <a href="../" class="md-nav__link ">
              
  
  <span class="md-ellipsis">
    Reference
  </span>

</a>
            
              
              <label class="md-nav__link " for="__nav_3" id="__nav_3_label" tabindex="">
                <span class="md-nav__icon md-icon"></span>
              </label>
            
          </div>
        
        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="true">
          <label class="md-nav__title" for="__nav_3">
            <span class="md-nav__icon md-icon"></span>
            Reference
          </label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
            
              
                
  
  
  
  
    <li class="md-nav__item">
      <a href="../derivepassphrase.1/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    Man page: derivepassphrase
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../derivepassphrase-vault.1/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    Man page: derivepassphrase-vault
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../derivepassphrase-export.1/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    Man page: derivepassphrase-export
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../derivepassphrase-export-vault.1/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    Man page: derivepassphrase-export-vault
  </span>

</a>
    </li>

<li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
      
        
        
        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_6" checked>
        
          
          <label class="md-nav__link" for="__nav_3_6" id="__nav_3_6_label" tabindex="">
            
  
  <span class="md-ellipsis">
    Module derivepassphrase
  </span>

<span class="md-nav__icon md-icon"></span>
          </label>
        
        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_6_label" aria-expanded="true">
          <label class="md-nav__title" for="__nav_3_6">
            <span class="md-nav__icon md-icon"></span>
            Module derivepassphrase
          </label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
                
  
  
  
  
    <li class="md-nav__item">
      <a href="../derivepassphrase.cli/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    Submodule cli
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../derivepassphrase.exporter/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    Subpackage exporter
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../derivepassphrase.sequin/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    Submodule sequin
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../derivepassphrase.ssh_agent/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    Submodule ssh_agent
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../derivepassphrase._types/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    Submodule _types
  </span>

</a>
    </li>

<li class="md-nav__item md-nav__item--active">
      
      <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
      
      
      
        <label class="md-nav__link md-nav__link--active" for="__toc">
          
  
  <span class="md-ellipsis">
    Submodule vault
  </span>

<span class="md-nav__icon md-icon"></span>
        </label>
      
      <a href="./" class="md-nav__link md-nav__link--active">
        
  
  <span class="md-ellipsis">
    Submodule vault
  </span>

</a>

<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
  
  
  
  
    <label class="md-nav__title" for="__toc">
      <span class="md-nav__icon md-icon"></span>
      Table of contents
    </label>
    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase.vault" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-module"></code>&nbsp;vault
    </span>
  </a>
  
    <nav class="md-nav" aria-label=" vault">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.vault.Vault" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;Vault
    </span>
  </a>
  
    <nav class="md-nav" aria-label=" Vault">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.vault.Vault.create_hash" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;create_hash
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.vault.Vault.generate" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;generate
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.vault.Vault.phrase_from_key" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;phrase_from_key
    </span>
  </a>
  
</li>
        
      </ul>
    </nav>
  
</li>
        
      </ul>
    </nav>
  
</li>
      
    </ul>
  
</nav>
      
    </li>

</ul>
        </nav>
      
    </li>

<li class="md-nav__item">
      <a href="../../changelog/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    Changelog
  </span>

</a>
    </li>

</ul>
</nav>
                  </div>
                </div>
              </div>
            
            
              
              <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
                <div class="md-sidebar__scrollwrap">
                  <div class="md-sidebar__inner">

<h1>Submodule vault</h1>

<h2 id="derivepassphrase.vault" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-module"></code>            <span class="doc doc-object-name doc-module-name">derivepassphrase.vault</span>

<p>Python port of the vault(1) password generation scheme.</p>

<h3 id="derivepassphrase.vault.Vault" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>            <span class="doc doc-object-name doc-class-name">Vault</span>

<a href="#derivepassphrase.vault.Vault" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">Vault</span><span class="p">(</span>
    <span class="o">*</span><span class="p">,</span>
    <span class="n">phrase</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a></span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytearray">bytearray</a></span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span> <span class="o">=</span> <span class="sa">b</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
    <span class="n">length</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#int">int</a></span> <span class="o">=</span> <span class="mi">20</span><span class="p">,</span>
    <span class="n">repeat</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#int">int</a></span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span>
    <span class="n">lower</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#int">int</a></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
    <span class="n">upper</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#int">int</a></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
    <span class="n">number</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#int">int</a></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
    <span class="n">space</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#int">int</a></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
    <span class="n">dash</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#int">int</a></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
    <span class="n">symbol</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#int">int</a></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>
<span class="p">)</span>
</code></pre></div>

<p>A work-alike of James Coglan&rsquo;s vault.</p>
<p>Store settings for generating (actually: deriving) passphrases for
named services, with various constraints, given only a master
passphrase.  Also, actually generate the passphrase.  The derivation
is deterministic and non-secret; only the master passphrase need be
kept secret.  The implementation is compatible with <a href="https://www.npmjs.com/package/vault">vault</a>.</p>
<p><a href="https://blog.jcoglan.com/2012/07/16/designing-vaults-generator-algorithm/">James Coglan explains the passphrase derivation algorithm in great
detail</a> in his blog post on said topic: A principally
infinite bit stream is obtained by running a key-derivation function
on the master passphrase and the service name, then this bit stream
is fed into a <a class="autorefs autorefs-internal" href="../derivepassphrase.sequin/#derivepassphrase.sequin.Sequin">sequin.Sequin</a> to generate random numbers in the
correct range, and finally these random numbers select passphrase
characters until the desired length is reached.</p>

<p><span class="doc-section-title">Parameters:</span></p>
    <table>
      <thead>
        <tr>
          <th>Name</th>
          <th>Type</th>
          <th>Description</th>
          <th>Default</th>
        </tr>
      </thead>
      <tbody>
          <tr class="doc-section-item">
            <td>
                <code>phrase</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a> | <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytearray">bytearray</a> | <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The master passphrase from which to derive the service
passphrases.  If a string, then the UTF-8 encoding of
the string is used.</p>
              </div>
            </td>
            <td>
                  <code>b&#39;&#39;</code>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>length</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#int">int</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>Desired passphrase length.</p>
              </div>
            </td>
            <td>
                  <code>20</code>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>repeat</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#int">int</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The maximum number of immediate character repetitions
allowed in the passphrase.  Disabled if set to 0.</p>
              </div>
            </td>
            <td>
                  <code>0</code>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>lower</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#int">int</a> | None</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>Optional constraint on ASCII lowercase characters.  If
positive, include this many lowercase characters
somewhere in the passphrase.  If 0, avoid lowercase
characters altogether.</p>
              </div>
            </td>
            <td>
                  <code>None</code>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>upper</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#int">int</a> | None</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>Same as <code>lower</code>, but for ASCII uppercase characters.</p>
              </div>
            </td>
            <td>
                  <code>None</code>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>number</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#int">int</a> | None</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>Same as <code>lower</code>, but for ASCII digits.</p>
              </div>
            </td>
            <td>
                  <code>None</code>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>space</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#int">int</a> | None</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>Same as <code>lower</code>, but for the space character.</p>
              </div>
            </td>
            <td>
                  <code>None</code>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>dash</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#int">int</a> | None</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>Same as <code>lower</code>, but for the hyphen-minus and underscore
characters.</p>
              </div>
            </td>
            <td>
                  <code>None</code>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>symbol</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#int">int</a> | None</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>Same as <code>lower</code>, but for all other hitherto unlisted
ASCII printable characters (except backquote).</p>
              </div>
            </td>
            <td>
                  <code>None</code>
            </td>
          </tr>
      </tbody>
    </table>

<p><span class="doc-section-title">Raises:</span></p>
    <table>
      <thead>
        <tr>
          <th>Type</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/exceptions.html#ValueError">ValueError</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>Conflicting passphrase constraints.  Permit more
characters, or increase the desired passphrase length.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

<details class="warning" open>
  <summary>Warning</summary>
  <p>Because of repetition constraints, it is not always possible
to detect conflicting passphrase constraints at construction
time.</p>
</details>

<h4 id="derivepassphrase.vault.Vault.create_hash" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-method"></code>            <span class="doc doc-object-name doc-function-name">create_hash</span>

<span class="doc doc-labels">
      <small class="doc doc-label doc-label-classmethod"><code>classmethod</code></small>
  </span>

<a href="#derivepassphrase.vault.Vault.create_hash" class="headerlink" title="Permanent link">&para;</a></h4>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">create_hash</span><span class="p">(</span>
    <span class="n">phrase</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a></span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytearray">bytearray</a></span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span><span class="p">,</span>
    <span class="n">service</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a></span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytearray">bytearray</a></span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span><span class="p">,</span>
    <span class="o">*</span><span class="p">,</span>
    <span class="n">length</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#int">int</a></span> <span class="o">=</span> <span class="mi">32</span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a></span>
</code></pre></div>

<p>Create a pseudorandom byte stream from phrase and service.</p>
<p>Create a pseudorandom byte stream from <code>phrase</code> and <code>service</code> by
feeding them into the key-derivation function PBKDF2
(8 iterations, using SHA-1).</p>

<p><span class="doc-section-title">Returns:</span></p>
    <table>
      <thead>
        <tr>
          <th>Type</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>A pseudorandom byte string of length <code>length</code>.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

<details class="note" open>
  <summary>Note</summary>
  <p>Shorter values returned from this method (with the same key
and message) are prefixes of longer values returned from
this method.  (This property is inherited from the
underlying PBKDF2 function.)  It is thus safe (if slow) to
call this method with the same input with ever-increasing
target lengths.</p>
</details>

<p><span class="doc-section-title">Examples:</span></p>
    <div class="highlight"><pre><span></span><code><span class="gp">&gt;&gt;&gt; </span><span class="c1"># See also Vault.phrase_from_key examples.</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">phrase</span> <span class="o">=</span> <span class="nb">bytes</span><span class="o">.</span><span class="n">fromhex</span><span class="p">(</span><span class="s1">&#39;&#39;&#39;</span>
<span class="gp">... </span><span class="s1">00 00 00 0b 73 73 68 2d 65 64 32 35 35 31 39</span>
<span class="gp">... </span><span class="s1">00 00 00 40</span>
<span class="gp">... </span><span class="s1">f0 98 19 80 6c 1a 97 d5 26 03 6e cc e3 65 8f 86</span>
<span class="gp">... </span><span class="s1">66 07 13 19 13 09 21 33 33 f9 e4 36 53 1d af fd</span>
<span class="gp">... </span><span class="s1">0d 08 1f ec f8 73 9b 8c 5f 55 39 16 7c 53 54 2c</span>
<span class="gp">... </span><span class="s1">1e 52 bb 30 ed 7f 89 e2 2f 69 51 55 d8 9e a6 02</span>
<span class="gp">... </span><span class="s1">&#39;&#39;&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Vault</span><span class="o">.</span><span class="n">create_hash</span><span class="p">(</span><span class="n">phrase</span><span class="p">,</span> <span class="s1">&#39;some_service&#39;</span><span class="p">,</span> <span class="n">length</span><span class="o">=</span><span class="mi">4</span><span class="p">)</span>
<span class="go">b&#39;M\xb1&lt;S&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Vault</span><span class="o">.</span><span class="n">create_hash</span><span class="p">(</span><span class="n">phrase</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;some_service&#39;</span><span class="p">,</span> <span class="n">length</span><span class="o">=</span><span class="mi">16</span><span class="p">)</span>
<span class="go">b&#39;M\xb1&lt;S\x827E\xd1M\xaf\xf8~\xc8n\x10\xcc&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Vault</span><span class="o">.</span><span class="n">create_hash</span><span class="p">(</span><span class="n">phrase</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;NOSUCHSERVICE&#39;</span><span class="p">,</span> <span class="n">length</span><span class="o">=</span><span class="mi">16</span><span class="p">)</span>
<span class="go">b&#39;\x1c\xc3\x9c\xd9\xb6\x1a\x99CS\x07\xc41\xf4\x85#s&#39;</span>
</code></pre></div>

</div>

<h4 id="derivepassphrase.vault.Vault.generate" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-method"></code>            <span class="doc doc-object-name doc-function-name">generate</span>

<a href="#derivepassphrase.vault.Vault.generate" class="headerlink" title="Permanent link">&para;</a></h4>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">generate</span><span class="p">(</span>
    <span class="n">service_name</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a></span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytearray">bytearray</a></span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span><span class="p">,</span>
    <span class="o">/</span><span class="p">,</span>
    <span class="o">*</span><span class="p">,</span>
    <span class="n">phrase</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a></span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytearray">bytearray</a></span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span> <span class="o">=</span> <span class="sa">b</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a></span>
</code></pre></div>

<p>Generate a service passphrase.</p>

<p><span class="doc-section-title">Returns:</span></p>
    <table>
      <thead>
        <tr>
          <th>Type</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The service passphrase.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

<p><span class="doc-section-title">Examples:</span></p>
    <div class="highlight"><pre><span></span><code><span class="gp">&gt;&gt;&gt; </span><span class="n">phrase</span> <span class="o">=</span> <span class="sa">b</span><span class="s1">&#39;She cells C shells bye the sea shoars&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># Using default options in constructor.</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Vault</span><span class="p">(</span><span class="n">phrase</span><span class="o">=</span><span class="n">phrase</span><span class="p">)</span><span class="o">.</span><span class="n">generate</span><span class="p">(</span><span class="sa">b</span><span class="s1">&#39;google&#39;</span><span class="p">)</span>
<span class="go">b&#39;: 4TVH#5:aZl8LueOT\\{&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># Also possible:</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Vault</span><span class="p">()</span><span class="o">.</span><span class="n">generate</span><span class="p">(</span><span class="sa">b</span><span class="s1">&#39;google&#39;</span><span class="p">,</span> <span class="n">phrase</span><span class="o">=</span><span class="n">phrase</span><span class="p">)</span>
<span class="go">b&#39;: 4TVH#5:aZl8LueOT\\{&#39;</span>
</code></pre></div>
    <p>Conflicting constraints are sometimes only found during
generation.</p>
    <div class="highlight"><pre><span></span><code><span class="gp">&gt;&gt;&gt; </span><span class="c1"># Note: no error here...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">v</span> <span class="o">=</span> <span class="n">Vault</span><span class="p">(</span>
<span class="gp">... </span>    <span class="n">lower</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span>
<span class="gp">... </span>    <span class="n">upper</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span>
<span class="gp">... </span>    <span class="n">number</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span>
<span class="gp">... </span>    <span class="n">space</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span>
<span class="gp">... </span>    <span class="n">dash</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span>
<span class="gp">... </span>    <span class="n">symbol</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span>
<span class="gp">... </span>    <span class="n">repeat</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span>
<span class="gp">... </span>    <span class="n">length</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span>
<span class="gp">... </span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># ... but here.</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">v</span><span class="o">.</span><span class="n">generate</span><span class="p">(</span>
<span class="gp">... </span>    <span class="s1">&#39;0&#39;</span><span class="p">,</span> <span class="n">phrase</span><span class="o">=</span><span class="sa">b</span><span class="s1">&#39;</span><span class="se">\x00</span><span class="s1">&#39;</span>
<span class="gp">... </span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="w">    </span><span class="o">...</span>
<span class="gr">ValueError</span>: <span class="n">no allowed characters left</span>
</code></pre></div>

</div>

<h4 id="derivepassphrase.vault.Vault.phrase_from_key" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-method"></code>            <span class="doc doc-object-name doc-function-name">phrase_from_key</span>

<span class="doc doc-labels">
      <small class="doc doc-label doc-label-classmethod"><code>classmethod</code></small>
  </span>

<a href="#derivepassphrase.vault.Vault.phrase_from_key" class="headerlink" title="Permanent link">&para;</a></h4>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">phrase_from_key</span><span class="p">(</span><span class="n">key</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a></span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytearray">bytearray</a></span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a></span>
</code></pre></div>

<p>Obtain the master passphrase from a configured SSH key.</p>
<p>vault allows the usage of certain SSH keys to derive a master
passphrase, by signing the vault UUID with the SSH key.  The key
type must ensure that signatures are deterministic.</p>

<p><span class="doc-section-title">Returns:</span></p>
    <table>
      <thead>
        <tr>
          <th>Type</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The signature of the vault UUID under this key, unframed but
encoded in base64.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

<p><span class="doc-section-title">Raises:</span></p>
    <table>
      <thead>
        <tr>
          <th>Type</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/exceptions.html#ValueError">ValueError</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The SSH key is principally unsuitable for this use case.
Usually this means that the signature is not
deterministic.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

<p><span class="doc-section-title">Examples:</span></p>
    <div class="highlight"><pre><span></span><code><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">base64</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># Actual Ed25519 test public key.</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">public_key</span> <span class="o">=</span> <span class="nb">bytes</span><span class="o">.</span><span class="n">fromhex</span><span class="p">(</span><span class="s1">&#39;&#39;&#39;</span>
<span class="gp">... </span><span class="s1">00 00 00 0b 73 73 68 2d 65 64 32 35 35 31 39</span>
<span class="gp">... </span><span class="s1">00 00 00 20</span>
<span class="gp">... </span><span class="s1">81 78 81 68 26 d6 02 48 5f 0f ff 32 48 6f e4 c1</span>
<span class="gp">... </span><span class="s1">30 89 dc 1c 6a 45 06 09 e9 09 0f fb c2 12 69 76</span>
<span class="gp">... </span><span class="s1">&#39;&#39;&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">expected_sig_raw</span> <span class="o">=</span> <span class="nb">bytes</span><span class="o">.</span><span class="n">fromhex</span><span class="p">(</span><span class="s1">&#39;&#39;&#39;</span>
<span class="gp">... </span><span class="s1">00 00 00 0b 73 73 68 2d 65 64 32 35 35 31 39</span>
<span class="gp">... </span><span class="s1">00 00 00 40</span>
<span class="gp">... </span><span class="s1">f0 98 19 80 6c 1a 97 d5 26 03 6e cc e3 65 8f 86</span>
<span class="gp">... </span><span class="s1">66 07 13 19 13 09 21 33 33 f9 e4 36 53 1d af fd</span>
<span class="gp">... </span><span class="s1">0d 08 1f ec f8 73 9b 8c 5f 55 39 16 7c 53 54 2c</span>
<span class="gp">... </span><span class="s1">1e 52 bb 30 ed 7f 89 e2 2f 69 51 55 d8 9e a6 02</span>
<span class="gp">... </span><span class="s1">&#39;&#39;&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># Raw Ed25519 signatures are 64 bytes long.</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">signature_blob</span> <span class="o">=</span> <span class="n">expected_sig_raw</span><span class="p">[</span><span class="o">-</span><span class="mi">64</span><span class="p">:]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">phrase</span> <span class="o">=</span> <span class="n">base64</span><span class="o">.</span><span class="n">standard_b64encode</span><span class="p">(</span><span class="n">signature_blob</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Vault</span><span class="o">.</span><span class="n">phrase_from_key</span><span class="p">(</span><span class="n">phrase</span><span class="p">)</span> <span class="o">==</span> <span class="n">expected</span>
<span class="go">True</span>
</code></pre></div>

</div>

</article>
            </div>
          
          
        </div>
        
      </main>
      
        <footer class="md-footer">
  
    
      
      <nav class="md-footer__inner md-grid" aria-label="Footer" >
        
          
          <a href="../derivepassphrase._types/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Submodule _types">
            <div class="md-footer__button md-icon">
              
              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
            </div>
            <div class="md-footer__title">
              <span class="md-footer__direction">
                Previous
              </span>
              <div class="md-ellipsis">
                Submodule _types
              </div>
            </div>
          </a>
        
        
          
          <a href="../../changelog/" class="md-footer__link md-footer__link--next" aria-label="Next: Changelog">
            <div class="md-footer__title">
              <span class="md-footer__direction">
                Next
              </span>
              <div class="md-ellipsis">
                Changelog
              </div>
            </div>
            <div class="md-footer__button md-icon">
              
              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg>
            </div>
          </a>
        
      </nav>
    
  
  <div class="md-footer-meta md-typeset">
    <div class="md-footer-meta__inner md-grid">
      <div class="md-copyright">
  
    <div class="md-copyright__highlight">
      Copyright &copy; 2024 Marco Ricci (the-13th-letter)
    </div>
  
  
    Made with
    <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
      Material for MkDocs
    </a>
    and
    <a href="https://mkdocstrings.github.io/python/" target="_blank" rel="noopener">
        mkdocstrings-python
    </a>
  
</div>
      
    </div>
  </div>
</footer>
      
    </div>
    <div class="md-dialog" data-md-component="dialog">
      <div class="md-dialog__inner md-typeset"></div>
    </div>
    
    
    
    
  </body>
</html>

derivepassphrase.git

Deployed ffee25004de8 to 0.x with MkDocs 1.6.1 and mike 2.1.3