0.x/reference/derivepassphrase.exporter/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.exporter/">
      
      
        <link rel="prev" href="../derivepassphrase.cli/">
      
      
        <link rel="next" href="../derivepassphrase.sequin/">
      
      
      <link rel="icon" href="../../assets/images/favicon.png">
      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.5.39">
    
    
      
        <title>Subpackage exporter - 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 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">
    Subpackage exporter
  </span>

<span class="md-nav__icon md-icon"></span>
        </label>
      
      <a href="./" class="md-nav__link md-nav__link--active">
        
  
  <span class="md-ellipsis">
    Subpackage exporter
  </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.exporter" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-module"></code>&nbsp;exporter
    </span>
  </a>
  
    <nav class="md-nav" aria-label=" exporter">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.get_vault_key" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;get_vault_key
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.get_vault_path" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;get_vault_path
    </span>
  </a>
  
</li>
        
      </ul>
    </nav>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.storeroom" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-module"></code>&nbsp;storeroom
    </span>
  </a>
  
    <nav class="md-nav" aria-label=" storeroom">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.storeroom.KeyPair" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;KeyPair
    </span>
  </a>
  
    <nav class="md-nav" aria-label=" KeyPair">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.storeroom.KeyPair.encryption_key" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;encryption_key
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.storeroom.KeyPair.signing_key" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;signing_key
    </span>
  </a>
  
</li>
        
      </ul>
    </nav>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.storeroom.MasterKeys" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;MasterKeys
    </span>
  </a>
  
    <nav class="md-nav" aria-label=" MasterKeys">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.storeroom.MasterKeys.hashing_key" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;hashing_key
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.storeroom.MasterKeys.encryption_key" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;encryption_key
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.storeroom.MasterKeys.signing_key" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;signing_key
    </span>
  </a>
  
</li>
        
      </ul>
    </nav>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.storeroom.derive_master_keys_keys" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;derive_master_keys_keys
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.storeroom.decrypt_master_keys_data" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;decrypt_master_keys_data
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.storeroom.decrypt_session_keys" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;decrypt_session_keys
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.storeroom.decrypt_contents" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;decrypt_contents
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.storeroom.decrypt_bucket_item" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;decrypt_bucket_item
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.storeroom.decrypt_bucket_file" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;decrypt_bucket_file
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.storeroom.export_storeroom_data" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;export_storeroom_data
    </span>
  </a>
  
</li>
        
      </ul>
    </nav>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.vault_native" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-module"></code>&nbsp;vault_native
    </span>
  </a>
  
    <nav class="md-nav" aria-label=" vault_native">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.vault_native.VaultNativeConfigParser" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;VaultNativeConfigParser
    </span>
  </a>
  
    <nav class="md-nav" aria-label=" VaultNativeConfigParser">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.vault_native.VaultNativeConfigParser.__call__" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;__call__
    </span>
  </a>
  
</li>
        
      </ul>
    </nav>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.vault_native.VaultNativeV03ConfigParser" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;VaultNativeV03ConfigParser
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.vault_native.VaultNativeV02ConfigParser" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;VaultNativeV02ConfigParser
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase.exporter.vault_native.export_vault_native_data" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;export_vault_native_data
    </span>
  </a>
  
</li>
        
      </ul>
    </nav>
  
</li>
      
    </ul>
  
</nav>
      
    </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">
      <a href="../derivepassphrase.vault/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    Submodule vault
  </span>

</a>
    </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>Subpackage exporter</h1>

<h2 id="derivepassphrase.exporter" 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.exporter</span>

<p>Foreign configuration exporter for derivepassphrase.</p>

<h3 id="derivepassphrase.exporter.get_vault_key" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">get_vault_key</span>

<a href="#derivepassphrase.exporter.get_vault_key" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">get_vault_key</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>Automatically determine the vault(1) master key/password.</p>
<p>Query the <code>VAULT_KEY</code>, <code>LOGNAME</code>, <code>USER</code> and <code>USERNAME</code> environment
variables, in that order.  This is the same algorithm that vault
uses.</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 master key/password.  This is generally used as input to
a key-derivation function to determine the <em>actual</em> encryption
and signing keys for the vault configuration.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

</div>

<h3 id="derivepassphrase.exporter.get_vault_path" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">get_vault_path</span>

<a href="#derivepassphrase.exporter.get_vault_path" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">get_vault_path</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#str">str</a></span> <span class="o">|</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" title="os.PathLike" href="https://docs.python.org/3/library/os.html#os.PathLike">PathLike</a></span>
</code></pre></div>

<p>Automatically determine the vault(1) configuration path.</p>
<p>Query the <code>VAULT_PATH</code> environment variable, or default to
<code>~/.vault</code>.  This is the same algorithm that vault uses.  If not
absolute, then <code>VAULT_PATH</code> is relative to the home directory.</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#str">str</a> | <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a> | <a class="autorefs autorefs-external" title="os.PathLike" href="https://docs.python.org/3/library/os.html#os.PathLike">PathLike</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The vault configuration path.  Depending on the vault version,
this may be a file or a directory.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

</div>

<h2 id="derivepassphrase.exporter.storeroom" 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.exporter.storeroom</span>

<p>Exporter for the vault &ldquo;storeroom&rdquo; configuration format.</p>
<p>The &ldquo;storeroom&rdquo; format is the experimental format used in alpha and beta
versions of vault beyond v0.3.0.  The configuration is stored as
a separate directory, which acts like a hash table (i.e. has named
slots) and provides an impure quasi-filesystem interface.  Each hash
table entry is separately encrypted and authenticated.  James Coglan
designed this format to avoid concurrent write issues when updating or
synchronizing the vault configuration with e.g. a cloud service.</p>
<p>The public interface is the <a class="autorefs autorefs-internal" href="#derivepassphrase.exporter.storeroom.export_storeroom_data"><code>export_storeroom_data</code></a> function.
Multiple <em>non-public</em> functions are additionally documented here for
didactical and educational reasons, but they are not part of the module
API, are subject to change without notice (including removal), and
should <em>not</em> be used or relied on.</p>

<h3 id="derivepassphrase.exporter.storeroom.KeyPair" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>            <span class="doc doc-object-name doc-class-name">KeyPair</span>

<div class="doc doc-contents ">
            <p class="doc doc-class-bases">
              Bases: <code><a class="autorefs autorefs-external" title="typing.TypedDict" href="https://docs.python.org/3/library/typing.html#typing.TypedDict">TypedDict</a></code></p>

<p>A pair of AES256 keys, one for encryption and one for signing.</p>

<h4 id="derivepassphrase.exporter.storeroom.KeyPair.encryption_key" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>            <span class="doc doc-object-name doc-attribute-name">encryption_key</span>

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

<a href="#derivepassphrase.exporter.storeroom.KeyPair.encryption_key" class="headerlink" title="Permanent link">&para;</a></h4>
<div class="doc-signature highlight"><pre><span></span><code><span class="n">encryption_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>
</code></pre></div>

</div>

<h4 id="derivepassphrase.exporter.storeroom.KeyPair.signing_key" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>            <span class="doc doc-object-name doc-attribute-name">signing_key</span>

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

<a href="#derivepassphrase.exporter.storeroom.KeyPair.signing_key" class="headerlink" title="Permanent link">&para;</a></h4>
<div class="doc-signature highlight"><pre><span></span><code><span class="n">signing_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>
</code></pre></div>

</div>

<h3 id="derivepassphrase.exporter.storeroom.MasterKeys" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>            <span class="doc doc-object-name doc-class-name">MasterKeys</span>

<p>A triple of AES256 keys, for encryption, signing and hashing.</p>

<p><span class="doc-section-title">Attributes:</span></p>
    <table>
      <thead>
        <tr>
          <th>Name</th>
          <th>Type</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
          <tr class="doc-section-item">
            <td><code><a class="autorefs autorefs-internal" title="derivepassphrase.exporter.storeroom.MasterKeys.hashing_key" href="#derivepassphrase.exporter.storeroom.MasterKeys.hashing_key">hashing_key</a></code></td>
            <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>AES256 key, used for hashing with HMAC-SHA256 to derive
a hash table slot for an item.</p>
              </div>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td><code><a class="autorefs autorefs-internal" title="derivepassphrase.exporter.storeroom.MasterKeys.encryption_key" href="#derivepassphrase.exporter.storeroom.MasterKeys.encryption_key">encryption_key</a></code></td>
            <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>AES256 key, used for encryption with AES256-CBC (with PKCS#7
padding).</p>
              </div>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td><code><a class="autorefs autorefs-internal" title="derivepassphrase.exporter.storeroom.MasterKeys.signing_key" href="#derivepassphrase.exporter.storeroom.MasterKeys.signing_key">signing_key</a></code></td>
            <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>AES256 key, used for signing with HMAC-SHA256.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

<h4 id="derivepassphrase.exporter.storeroom.MasterKeys.hashing_key" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>            <span class="doc doc-object-name doc-attribute-name">hashing_key</span>

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

<a href="#derivepassphrase.exporter.storeroom.MasterKeys.hashing_key" class="headerlink" title="Permanent link">&para;</a></h4>
<div class="doc-signature highlight"><pre><span></span><code><span class="n">hashing_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>
</code></pre></div>

</div>

<h4 id="derivepassphrase.exporter.storeroom.MasterKeys.encryption_key" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>            <span class="doc doc-object-name doc-attribute-name">encryption_key</span>

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

<a href="#derivepassphrase.exporter.storeroom.MasterKeys.encryption_key" class="headerlink" title="Permanent link">&para;</a></h4>
<div class="doc-signature highlight"><pre><span></span><code><span class="n">encryption_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>
</code></pre></div>

</div>

<h4 id="derivepassphrase.exporter.storeroom.MasterKeys.signing_key" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>            <span class="doc doc-object-name doc-attribute-name">signing_key</span>

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

<a href="#derivepassphrase.exporter.storeroom.MasterKeys.signing_key" class="headerlink" title="Permanent link">&para;</a></h4>
<div class="doc-signature highlight"><pre><span></span><code><span class="n">signing_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>
</code></pre></div>

</div>

<h3 id="derivepassphrase.exporter.storeroom.derive_master_keys_keys" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">derive_master_keys_keys</span>

<a href="#derivepassphrase.exporter.storeroom.derive_master_keys_keys" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">derive_master_keys_keys</span><span class="p">(</span>
    <span class="n">password</span><span class="p">:</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="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a></span><span class="p">,</span> <span class="n">iterations</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="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-internal" title="derivepassphrase.exporter.storeroom.KeyPair" href="#derivepassphrase.exporter.storeroom.KeyPair">KeyPair</a></span>
</code></pre></div>

<p>Derive encryption and signing keys for the master keys data.</p>
<p>The master password is run through a key derivation function to
obtain a 64-byte string, which is then split to yield two 32-byte
keys.  The key derivation function is PBKDF2, using HMAC-SHA1 and
salted with the storeroom master keys UUID.</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-internal" title="derivepassphrase.exporter.storeroom.KeyPair" href="#derivepassphrase.exporter.storeroom.KeyPair">KeyPair</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>A 2-tuple of keys, the encryption key and the signing key, to
decrypt and verify the master keys data with.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

<details class="warning" open>
  <summary>Warning</summary>
  <p>Non-public function, provided for didactical and educational
purposes only.  Subject to change without notice, including
removal.</p>
</details>
    </div>

</div>

<h3 id="derivepassphrase.exporter.storeroom.decrypt_master_keys_data" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">decrypt_master_keys_data</span>

<a href="#derivepassphrase.exporter.storeroom.decrypt_master_keys_data" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">decrypt_master_keys_data</span><span class="p">(</span>
    <span class="n">data</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="p">,</span> <span class="n">keys</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="derivepassphrase.exporter.storeroom.KeyPair" href="#derivepassphrase.exporter.storeroom.KeyPair">KeyPair</a></span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-internal" title="derivepassphrase.exporter.storeroom.MasterKeys" href="#derivepassphrase.exporter.storeroom.MasterKeys">MasterKeys</a></span>
</code></pre></div>

<p>Decrypt the master keys data.</p>
<p>The master keys data contains:</p>
<ul>
<li>a 16-byte IV,</li>
<li>a 96-byte AES256-CBC-encrypted payload, plus 16 further bytes of
  PKCS7 padding, and</li>
<li>a 32-byte MAC of the preceding 128 bytes.</li>
</ul>
<p>The decrypted payload itself consists of three 32-byte keys: the
hashing, encryption and signing keys, in that order.</p>
<p>The encrypted payload is encrypted with the encryption key, and the
MAC is created based on the signing key.  As per standard
cryptographic procedure, the MAC can be verified before attempting
to decrypt the payload.</p>
<p>Because the payload size is both fixed and a multiple of the cipher
blocksize, in this case, the PKCS7 padding always is <code>b'\x10' * 16</code>.</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-internal" title="derivepassphrase.exporter.storeroom.MasterKeys" href="#derivepassphrase.exporter.storeroom.MasterKeys">MasterKeys</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The master encryption, signing and hashing keys.</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" title="cryptography.exceptions.InvalidSignature" href="https://cryptography.readthedocs.io/en/latest/exceptions/#cryptography.exceptions.InvalidSignature">InvalidSignature</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The data does not contain a valid signature under the given
key.</p>
              </div>
            </td>
          </tr>
          <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 format is invalid, in a non-cryptographic way.  (For
example, it contains an unsupported version marker, or
unexpected extra contents, or invalid padding.)</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

</div>

<h3 id="derivepassphrase.exporter.storeroom.decrypt_session_keys" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">decrypt_session_keys</span>

<a href="#derivepassphrase.exporter.storeroom.decrypt_session_keys" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">decrypt_session_keys</span><span class="p">(</span>
    <span class="n">data</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="p">,</span> <span class="n">master_keys</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="derivepassphrase.exporter.storeroom.MasterKeys" href="#derivepassphrase.exporter.storeroom.MasterKeys">MasterKeys</a></span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-internal" title="derivepassphrase.exporter.storeroom.KeyPair" href="#derivepassphrase.exporter.storeroom.KeyPair">KeyPair</a></span>
</code></pre></div>

<p>Decrypt the bucket item&rsquo;s session keys.</p>
<p>The bucket item&rsquo;s session keys are single-use keys for encrypting
and signing a single item in the storage bucket.  The encrypted
session key data consists of:</p>
<ul>
<li>a 16-byte IV,</li>
<li>a 64-byte AES256-CBC-encrypted payload, plus 16 further bytes of
  PKCS7 padding, and</li>
<li>a 32-byte MAC of the preceding 96 bytes.</li>
</ul>
<p>The encrypted payload is encrypted with the master encryption key,
and the MAC is created with the master signing key.  As per standard
cryptographic procedure, the MAC can be verified before attempting
to decrypt the payload.</p>
<p>Because the payload size is both fixed and a multiple of the cipher
blocksize, in this case, the PKCS7 padding always is <code>b'\x10' * 16</code>.</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-internal" title="derivepassphrase.exporter.storeroom.KeyPair" href="#derivepassphrase.exporter.storeroom.KeyPair">KeyPair</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The bucket item&rsquo;s encryption and signing keys.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

</div>

<h3 id="derivepassphrase.exporter.storeroom.decrypt_contents" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">decrypt_contents</span>

<a href="#derivepassphrase.exporter.storeroom.decrypt_contents" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">decrypt_contents</span><span class="p">(</span>
    <span class="n">data</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="p">,</span> <span class="n">session_keys</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="derivepassphrase.exporter.storeroom.KeyPair" href="#derivepassphrase.exporter.storeroom.KeyPair">KeyPair</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>Decrypt the bucket item&rsquo;s contents.</p>
<p>The data consists of:</p>
<ul>
<li>a 16-byte IV,</li>
<li>a variable-sized AES256-CBC-encrypted payload (using PKCS7 padding
  on the inside), and</li>
<li>a 32-byte MAC of the preceding bytes.</li>
</ul>
<p>The encrypted payload is encrypted with the bucket item&rsquo;s session
encryption key, and the MAC is created with the bucket item&rsquo;s
session signing key.  As per standard cryptographic procedure, the
MAC can be verified before attempting to decrypt the payload.</p>

</div>

<h3 id="derivepassphrase.exporter.storeroom.decrypt_bucket_item" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">decrypt_bucket_item</span>

<a href="#derivepassphrase.exporter.storeroom.decrypt_bucket_item" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">decrypt_bucket_item</span><span class="p">(</span>
    <span class="n">bucket_item</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="p">,</span> <span class="n">master_keys</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="derivepassphrase.exporter.storeroom.MasterKeys" href="#derivepassphrase.exporter.storeroom.MasterKeys">MasterKeys</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>Decrypt a bucket item.</p>

</div>

<h3 id="derivepassphrase.exporter.storeroom.decrypt_bucket_file" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">decrypt_bucket_file</span>

<a href="#derivepassphrase.exporter.storeroom.decrypt_bucket_file" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">decrypt_bucket_file</span><span class="p">(</span>
    <span class="n">filename</span><span class="p">:</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">master_keys</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="derivepassphrase.exporter.storeroom.MasterKeys" href="#derivepassphrase.exporter.storeroom.MasterKeys">MasterKeys</a></span><span class="p">,</span>
    <span class="o">*</span><span class="p">,</span>
    <span class="n">root_dir</span><span class="p">:</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="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" title="os.PathLike" href="https://docs.python.org/3/library/os.html#os.PathLike">PathLike</a></span> <span class="o">=</span> <span class="s2">&quot;.&quot;</span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" title="collections.abc.Iterator" href="https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterator">Iterator</a></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="p">]</span>
</code></pre></div>

<p>Decrypt a complete bucket.</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>filename</code>
            </td>
            <td>
                  <code><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 bucket file&rsquo;s filename.</p>
              </div>
            </td>
            <td>
                <em>required</em>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>master_keys</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-internal" title="derivepassphrase.exporter.storeroom.MasterKeys" href="#derivepassphrase.exporter.storeroom.MasterKeys">MasterKeys</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The master keys.  Presumably these have previously been
obtained via the <a class="autorefs autorefs-internal" href="#derivepassphrase.exporter.storeroom.decrypt_master_keys_data"><code>decrypt_master_keys_data</code></a> function.</p>
              </div>
            </td>
            <td>
                <em>required</em>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>root_dir</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a> | <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a> | <a class="autorefs autorefs-external" title="os.PathLike" href="https://docs.python.org/3/library/os.html#os.PathLike">PathLike</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The root directory of the data store.  The filename is
interpreted relatively to this directory.</p>
              </div>
            </td>
            <td>
                  <code>&#39;.&#39;</code>
            </td>
          </tr>
      </tbody>
    </table>

<p><span class="doc-section-title">Yields:</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 decrypted bucket item.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

</div>

<h3 id="derivepassphrase.exporter.storeroom.export_storeroom_data" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">export_storeroom_data</span>

<a href="#derivepassphrase.exporter.storeroom.export_storeroom_data" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">export_storeroom_data</span><span class="p">(</span>
    <span class="n">storeroom_path</span><span class="p">:</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="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" title="os.PathLike" href="https://docs.python.org/3/library/os.html#os.PathLike">PathLike</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">master_keys_key</span><span class="p">:</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="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="kc">None</span> <span class="o">=</span> <span class="kc">None</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#dict">dict</a></span><span class="p">[</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"><a class="autorefs autorefs-external" title="typing.Any" href="https://docs.python.org/3/library/typing.html#typing.Any">Any</a></span><span class="p">]</span>
</code></pre></div>

<p>Export the full configuration stored in the storeroom.</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>storeroom_path</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a> | <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a> | <a class="autorefs autorefs-external" title="os.PathLike" href="https://docs.python.org/3/library/os.html#os.PathLike">PathLike</a> | None</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>Path to the storeroom; usually <code>~/.vault</code>.  If not given,
then query <a class="autorefs autorefs-internal" href="#derivepassphrase.exporter.get_vault_path"><code>exporter.get_vault_path</code></a> for the value.</p>
              </div>
            </td>
            <td>
                  <code>None</code>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>master_keys_key</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a> | <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a> | None</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>Encryption key/password for the master keys, usually the
username, or passed via the <code>VAULT_KEY</code> environment
variable.  If not given, then query
<a class="autorefs autorefs-internal" href="#derivepassphrase.exporter.get_vault_key"><code>exporter.get_vault_key</code></a> for the value.</p>
              </div>
            </td>
            <td>
                  <code>None</code>
            </td>
          </tr>
      </tbody>
    </table>

<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#dict">dict</a>[<a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a>, <a class="autorefs autorefs-external" title="typing.Any" href="https://docs.python.org/3/library/typing.html#typing.Any">Any</a>]</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The full configuration, as stored in the storeroom.</p>
<p>This may or may not be a valid configuration according to vault
or derivepassphrase.</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#RuntimeError">RuntimeError</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>Something went wrong during data collection, e.g. we
encountered unsupported or corrupted data in the storeroom.</p>
              </div>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" title="json.JSONDecodeError" href="https://docs.python.org/3/library/json.html#json.JSONDecodeError">JSONDecodeError</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>An internal JSON data structure failed to parse from disk.
The storeroom is probably corrupted.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

</div>

<h2 id="derivepassphrase.exporter.vault_native" 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.exporter.vault_native</span>

<p>Exporter for the vault native configuration format (v0.2 or v0.3).</p>
<p>The vault native formats are the configuration formats used by vault
v0.2 and v0.3.  The configuration is stored as a single encrypted file,
which is encrypted and authenticated.  v0.2 and v0.3 differ in some
details concerning key derivation and expected format of internal
structures, so they are <em>not</em> compatible.  v0.2 additionally contains
cryptographic weaknesses (API misuse of a key derivation function, and
a low-entropy method of generating initialization vectors for CBC block
encryption mode) and should thus be avoided if possible.</p>
<p>The public interface is the <a class="autorefs autorefs-internal" href="#derivepassphrase.exporter.vault_native.export_vault_native_data"><code>export_vault_native_data</code></a> function.
Multiple <em>non-public</em> classes are additionally documented here for
didactical and educational reasons, but they are not part of the module
API, are subject to change without notice (including removal), and
should <em>not</em> be used or relied on.</p>

<h3 id="derivepassphrase.exporter.vault_native.VaultNativeConfigParser" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>            <span class="doc doc-object-name doc-class-name">VaultNativeConfigParser</span>

<a href="#derivepassphrase.exporter.vault_native.VaultNativeConfigParser" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">VaultNativeConfigParser</span><span class="p">(</span>
    <span class="n">contents</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="typing_extensions.Buffer" href="https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.Buffer">Buffer</a></span><span class="p">,</span> <span class="n">password</span><span class="p">:</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="n"><a class="autorefs autorefs-external" title="typing_extensions.Buffer" href="https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.Buffer">Buffer</a></span>
<span class="p">)</span>
</code></pre></div>

<div class="doc doc-contents ">
            <p class="doc doc-class-bases">
              Bases: <code><a class="autorefs autorefs-external" title="abc.ABC" href="https://docs.python.org/3/library/abc.html#abc.ABC">ABC</a></code></p>

<p>A base parser for vault&rsquo;s native configuration format.</p>
<p>Certain details are specific to the respective vault versions, and
are abstracted out.  This class by itself is not instantiable
because of this.</p>

<details class="warning" open>
  <summary>Warning</summary>
  <p>Non-public class, provided for didactical and educational
purposes only. Subject to change without notice, including
removal.</p>
</details>

<p>Return the decrypted and parsed vault configuration.</p>

<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" title="cryptography.exceptions.InvalidSignature" href="https://cryptography.readthedocs.io/en/latest/exceptions/#cryptography.exceptions.InvalidSignature">InvalidSignature</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The encrypted configuration does not contain a valid
signature.</p>
              </div>
            </td>
          </tr>
          <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 format is invalid, in a non-cryptographic way.  (For
example, it contains an unsupported version marker, or
unexpected extra contents, or invalid padding.)</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

</div>

<h3 id="derivepassphrase.exporter.vault_native.VaultNativeV03ConfigParser" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>            <span class="doc doc-object-name doc-class-name">VaultNativeV03ConfigParser</span>

<a href="#derivepassphrase.exporter.vault_native.VaultNativeV03ConfigParser" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">VaultNativeV03ConfigParser</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="typing.Any" href="https://docs.python.org/3/library/typing.html#typing.Any">Any</a></span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="typing.Any" href="https://docs.python.org/3/library/typing.html#typing.Any">Any</a></span><span class="p">)</span>
</code></pre></div>

<div class="doc doc-contents ">
            <p class="doc doc-class-bases">
              Bases: <code><a class="autorefs autorefs-internal" title="derivepassphrase.exporter.vault_native.VaultNativeConfigParser" href="#derivepassphrase.exporter.vault_native.VaultNativeConfigParser">VaultNativeConfigParser</a></code></p>

<p>A parser for vault&rsquo;s native configuration format (v0.3).</p>
<p>This is the modern, pre-storeroom configuration format.</p>

</div>

<h3 id="derivepassphrase.exporter.vault_native.VaultNativeV02ConfigParser" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>            <span class="doc doc-object-name doc-class-name">VaultNativeV02ConfigParser</span>

<a href="#derivepassphrase.exporter.vault_native.VaultNativeV02ConfigParser" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">VaultNativeV02ConfigParser</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="typing.Any" href="https://docs.python.org/3/library/typing.html#typing.Any">Any</a></span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="typing.Any" href="https://docs.python.org/3/library/typing.html#typing.Any">Any</a></span><span class="p">)</span>
</code></pre></div>

<p>A parser for vault&rsquo;s native configuration format (v0.2).</p>
<p>This is the classic configuration format.  Compared to v0.3, it
contains an (accidental) API misuse for the generation of the master
keys, a low-entropy method of generating initialization vectors for
the AES-CBC encryption step, and extra layers of base64 encoding.
Because of these significantly weakened confidentiality guarantees,
v0.2 configurations should be upgraded to at least v0.3 as soon as
possible.</p>

</div>

<h3 id="derivepassphrase.exporter.vault_native.export_vault_native_data" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">export_vault_native_data</span>

<a href="#derivepassphrase.exporter.vault_native.export_vault_native_data" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">export_vault_native_data</span><span class="p">(</span>
    <span class="n">contents</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="typing_extensions.Buffer" href="https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.Buffer">Buffer</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">key</span><span class="p">:</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="n"><a class="autorefs autorefs-external" title="typing_extensions.Buffer" href="https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.Buffer">Buffer</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="o">*</span><span class="p">,</span>
    <span class="n">try_formats</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="collections.abc.Sequence" href="https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence">Sequence</a></span><span class="p">[</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="s2">&quot;v0.3&quot;</span><span class="p">,</span> <span class="s2">&quot;v0.2&quot;</span><span class="p">)</span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" title="typing.Any" href="https://docs.python.org/3/library/typing.html#typing.Any">Any</a></span>
</code></pre></div>

<p>Export the full configuration stored in vault native format.</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>contents</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" title="typing_extensions.Buffer" href="https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.Buffer">Buffer</a> | None</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The binary encrypted contents of the vault configuration
file.  If not given, then query
<a class="autorefs autorefs-internal" href="#derivepassphrase.exporter.get_vault_path"><code>exporter.get_vault_path</code></a> for the correct filename and
read the contents from there.</p>
<p>Note: On disk, these are usually stored in base64-encoded
form, not in the &ldquo;raw&rdquo; form as needed here.</p>
              </div>
            </td>
            <td>
                  <code>None</code>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>key</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a> | <a class="autorefs autorefs-external" title="typing_extensions.Buffer" href="https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.Buffer">Buffer</a> | None</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>Encryption key/password for the configuration file, usually
the username, or passed via the <code>VAULT_KEY</code> environment
variable.  If not given, then query
<a class="autorefs autorefs-internal" href="#derivepassphrase.exporter.get_vault_key"><code>exporter.get_vault_key</code></a> for the value.</p>
              </div>
            </td>
            <td>
                  <code>None</code>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>try_formats</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" title="collections.abc.Sequence" href="https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence">Sequence</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>A sequence of formats to try out, in order.  Each key must
be one of <code>v0.2</code> or <code>v0.3</code>.</p>
              </div>
            </td>
            <td>
                  <code>(&#39;v0.3&#39;, &#39;v0.2&#39;)</code>
            </td>
          </tr>
      </tbody>
    </table>

<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" title="typing.Any" href="https://docs.python.org/3/library/typing.html#typing.Any">Any</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The vault configuration, as recorded in the configuration file.</p>
<p>This may or may not be a valid configuration according to vault
or derivepassphrase.</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#RuntimeError">RuntimeError</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>Something went wrong during data collection, e.g. we
encountered unsupported or corrupted data in the storeroom.</p>
              </div>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" title="json.JSONDecodeError" href="https://docs.python.org/3/library/json.html#json.JSONDecodeError">JSONDecodeError</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>An internal JSON data structure failed to parse from disk.
The storeroom is probably corrupted.</p>
              </div>
            </td>
          </tr>
          <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 requested formats to try out are invalid, or the
encrypted contents aren&rsquo;t in any of the attempted
configuration formats.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

</div>

</article>
            </div>
          
          
        </div>
        
      </main>
      
        <footer class="md-footer">
  
    
      
      <nav class="md-footer__inner md-grid" aria-label="Footer" >
        
          
          <a href="../derivepassphrase.cli/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Submodule cli">
            <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 cli
              </div>
            </div>
          </a>
        
        
          
          <a href="../derivepassphrase.sequin/" class="md-footer__link md-footer__link--next" aria-label="Next: Submodule sequin">
            <div class="md-footer__title">
              <span class="md-footer__direction">
                Next
              </span>
              <div class="md-ellipsis">
                Submodule sequin
              </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