0.x/tutorials/basic-setup-passphrase/index.html (34d65a6) - 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/tutorials/basic-setup-passphrase/">
      
      
        <link rel="prev" href="../">
      
      
        <link rel="next" href="../../how-tos/">
      
      
      <link rel="icon" href="../../assets/images/favicon.png">
      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.5.42">
    
    
      
        <title>Setting up derivepassphrase vault for three accounts, with a master passphrase - derivepassphrase</title>
      
    
    
      <link rel="stylesheet" href="../../assets/stylesheets/main.0253249f.min.css">

</a>
    </li>

<li class="md-tabs__item md-tabs__item--active">
        <a href="../" class="md-tabs__link">
          
  
    
  
  Tutorials & Examples

</a>
      </li>

<li class="md-tabs__item">
        <a href="../../how-tos/" class="md-tabs__link">
          
  
    
  
  How-Tos

</a>
      </li>

<li class="md-tabs__item">
        <a href="../../reference/" 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--active md-nav__item--section md-nav__item--nested">
      
        
        
        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2" checked>
        
          
          
          <div class="md-nav__link md-nav__container">
            <a href="../" class="md-nav__link ">
              
  
  <span class="md-ellipsis">
    Tutorials & Examples
  </span>

</a>
            
              
              <label class="md-nav__link " for="__nav_2" id="__nav_2_label" tabindex="">
                <span class="md-nav__icon md-icon"></span>
              </label>
            
          </div>
        
        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="true">
          <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 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">
    Setting up derivepassphrase vault for three accounts, with a master passphrase
  </span>

<span class="md-nav__icon md-icon"></span>
        </label>
      
      <a href="./" class="md-nav__link md-nav__link--active">
        
  
  <span class="md-ellipsis">
    Setting up derivepassphrase vault for three accounts, with a master passphrase
  </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="#the-scenario" class="md-nav__link">
    <span class="md-ellipsis">
      The scenario
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#installing-derivepassphrase" class="md-nav__link">
    <span class="md-ellipsis">
      Installing derivepassphrase
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#choosing-a-master-passphrase" class="md-nav__link">
    <span class="md-ellipsis">
      Choosing a master passphrase
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#setting-up-the-email-account" class="md-nav__link">
    <span class="md-ellipsis">
      Setting up the email account
    </span>
  </a>
  
    <nav class="md-nav" aria-label="Setting up the email account">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#storing-the-settings-to-disk" class="md-nav__link">
    <span class="md-ellipsis">
      Storing the settings to disk
    </span>
  </a>
  
</li>
        
      </ul>
    </nav>
  
</li>
      
        <li class="md-nav__item">
  <a href="#setting-up-the-bank-account" class="md-nav__link">
    <span class="md-ellipsis">
      Setting up the bank account
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#setting-up-the-work-account" class="md-nav__link">
    <span class="md-ellipsis">
      Setting up the work account
    </span>
  </a>
  
    <nav class="md-nav" aria-label="Setting up the work account">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#complication-1-what-is-a-permitted-special-character" class="md-nav__link">
    <span class="md-ellipsis">
      Complication 1: What is a (permitted) &ldquo;special character&rdquo;?
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#complication-2-how-to-implement-passphrase-rotation" class="md-nav__link">
    <span class="md-ellipsis">
      Complication 2: How to implement passphrase rotation?
    </span>
  </a>
  
</li>
        
      </ul>
    </nav>
  
</li>
      
        <li class="md-nav__item">
  <a href="#summary" class="md-nav__link">
    <span class="md-ellipsis">
      Summary
    </span>
  </a>
  
</li>
      
    </ul>
  
</nav>
      
    </li>

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

</a>
            
              
              <label class="md-nav__link " for="__nav_3" id="__nav_3_label" tabindex="0">
                <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="false">
          <label class="md-nav__title" for="__nav_3">
            <span class="md-nav__icon md-icon"></span>
            How-Tos
          </label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
            
              
                
  
  
  
  
    <li class="md-nav__item">
      <a href="../../how-tos/ssh-key/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    How to set up derivepassphrase vault with an SSH key
  </span>

</a>
    </li>

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

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

</a>
            
              
              <label class="md-nav__link " for="__nav_4" id="__nav_4_label" tabindex="0">
                <span class="md-nav__icon md-icon"></span>
              </label>
            
          </div>
        
        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
          <label class="md-nav__title" for="__nav_4">
            <span class="md-nav__icon md-icon"></span>
            Reference
          </label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
            
              
                
  
  
  
  
    
    
      
        
      
        
      
        
      
        
      
    
    
      
      
        
      
    
    
    <li class="md-nav__item md-nav__item--nested">
      
        
        
        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4_2" >
        
          
          <label class="md-nav__link" for="__nav_4_2" id="__nav_4_2_label" tabindex="0">
            
  
  <span class="md-ellipsis">
    Man pages
  </span>

<span class="md-nav__icon md-icon"></span>
          </label>
        
        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_4_2_label" aria-expanded="false">
          <label class="md-nav__title" for="__nav_4_2">
            <span class="md-nav__icon md-icon"></span>
            Man pages
          </label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
                
  
  
  
  
    <li class="md-nav__item">
      <a href="../../reference/derivepassphrase.1/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    derivepassphrase(1)
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../../reference/derivepassphrase-vault.1/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    derivepassphrase-vault(1)
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../../reference/derivepassphrase-export.1/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    derivepassphrase-export(1)
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../../reference/derivepassphrase-export-vault.1/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    derivepassphrase-export-vault(1)
  </span>

</a>
    </li>

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

<li class="md-nav__item md-nav__item--nested">
      
        
        
        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4_3" >
        
          
          <label class="md-nav__link" for="__nav_4_3" id="__nav_4_3_label" tabindex="0">
            
  
  <span class="md-ellipsis">
    API docs: Module derivepassphrase
  </span>

<span class="md-nav__icon md-icon"></span>
          </label>
        
        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_4_3_label" aria-expanded="false">
          <label class="md-nav__title" for="__nav_4_3">
            <span class="md-nav__icon md-icon"></span>
            API docs: Module derivepassphrase
          </label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
                
  
  
  
  
    <li class="md-nav__item">
      <a href="../../reference/derivepassphrase.cli/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    Submodule cli
  </span>

</a>
    </li>

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

</a>
    </li>

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

</a>
    </li>

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

</a>
    </li>

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

</a>
    </li>

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

</a>
    </li>

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

<li class="md-nav__item md-nav__item--nested">
      
        
        
        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4_4" >
        
          
          <label class="md-nav__link" for="__nav_4_4" id="__nav_4_4_label" tabindex="0">
            
  
  <span class="md-ellipsis">
    Technical prerequisites
  </span>

<span class="md-nav__icon md-icon"></span>
          </label>
        
        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_4_4_label" aria-expanded="false">
          <label class="md-nav__title" for="__nav_4_4">
            <span class="md-nav__icon md-icon"></span>
            Technical prerequisites
          </label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
                
  
  
  
  
    <li class="md-nav__item">
      <a href="../../reference/prerequisites-ssh-key/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    Using derivepassphrase vault with an SSH key
  </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 id="setting-up-derivepassphrase-vault-for-three-accounts-with-a-master-passphrase">Setting up <code>derivepassphrase vault</code> for three accounts, with a master passphrase<a class="headerlink" href="#setting-up-derivepassphrase-vault-for-three-accounts-with-a-master-passphrase" title="Permanent link">&para;</a></h1>
<h2 id="the-scenario">The scenario<a class="headerlink" href="#the-scenario" title="Permanent link">&para;</a></h2>
<p>In this tutorial, we will setup <code>derivepassphrase</code> for three services, using a master passphrase and the standard <code>vault</code> passphrase derivation scheme.
We will assume the following three services with the following passphrase policies:</p>
<div class="grid cards">
<ul>
<li>
<p><strong>email account</strong></p>
<hr />
<ul>
<li>between 12 and 20 characters</li>
<li>no spaces</li>
<li>1 upper case letter, 1 lower case letter, 1 digit</li>
<li>no character may appear 3 times (or more) in a row</li>
</ul>
</li>
<li>
<p><strong>bank account</strong></p>
<hr />
<ul>
<li>only digits</li>
<li>exactly 5 digits</li>
<li>an additional one-time password via a hardware token (&ldquo;<a href="https://en.wikipedia.org/wiki/Two-factor_authentication">two-factor authentication</a>&rdquo;)</li>
</ul>
</li>
<li>
<p><strong>work account</strong></p>
<hr />
<ul>
<li>exactly 8 characters</li>
<li>no spaces</li>
<li>1 special character, 1 letter, 1 digit</li>
<li>must be changed every quarter (January, April, July and October) to a different value (&ldquo;passphrase rotation&rdquo; or &ldquo;rollover&rdquo;)</li>
<li>must actually be different from the previous <em>two</em> passphrases</li>
</ul>
</li>
</ul>
</div>
<h2 id="installing-derivepassphrase">Installing <code>derivepassphrase</code><a class="headerlink" href="#installing-derivepassphrase" title="Permanent link">&para;</a></h2>
<p>You will need Python 3, and a package installer such as <code>pip</code> (bundled with Python), <code>pipx</code> or similar.</p>
<hr />
<div class="tabbed-set tabbed-alternate" data-tabs="1:2"><input checked="checked" id="__tabbed_1_1" name="__tabbed_1" type="radio" /><input id="__tabbed_1_2" name="__tabbed_1" type="radio" /><div class="tabbed-labels"><label for="__tabbed_1_1">pip</label><label for="__tabbed_1_2">pipx</label></div>
<div class="tabbed-content">
<div class="tabbed-block">
<p>With <code>pip</code>, using a &ldquo;virtual enviroment&rdquo; at <code>~/.venv</code> to avoid clobbering our system configuration:</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>python3<span class="w"> </span>-m<span class="w"> </span>venv<span class="w"> </span>~/.venv
<span class="gp">$ </span>.<span class="w"> </span>~/.venv/bin/activate
<span class="gp">$ </span>pip<span class="w"> </span>install<span class="w"> </span>derivepassphrase
</code></pre></div>
</div>
<div class="tabbed-block">
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>pipx<span class="w"> </span>install<span class="w"> </span>derivepassphrase
</code></pre></div>
</div>
</div>
</div>
<hr />
<p>Check that the installation was successful.</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>devirepassphrase<span class="w"> </span>--version
<span class="go">derivepassphrase, version 0.3.0</span>
</code></pre></div>
<p>(…or similar output.)</p>
<h2 id="choosing-a-master-passphrase">Choosing a master passphrase<a class="headerlink" href="#choosing-a-master-passphrase" title="Permanent link">&para;</a></h2>
<p><code>derivepassphrase</code> uses a master passphrase <var>MP</var>, and derives all other passphrases <var>P</var> from <var>MP</var>.
We shall choose the master passphrase: <code>I am an insecure master passphrase, but easy to type.</code></p>
<h2 id="setting-up-the-email-account">Setting up the email account<a class="headerlink" href="#setting-up-the-email-account" title="Permanent link">&para;</a></h2>
<p>In <code>derivepassphrase</code>, each passphrase configuration contains a <em>service name</em>, which is how <code>derivepassphrase</code> distinguishes between configurations.
This service name can be chosen freely, but the resulting passphrase depends on the chosen service name.
For our email account, we choose the straightforward service name <code>email</code>.</p>
<p>We need to translate the passphrase policy into options for <code>derivepassphrase</code>:</p>
<ul>
<li>A policy &ldquo;(at least) <var>n</var> lower case letters&rdquo; translates to the option <code>-<span/>-lower <var>n</var></code>, for any <var>n</var> &gt; 0.
  Upper case letters (<code>--upper</code>), digits (<code>--number</code>), symbols (<code>--symbol</code>), spaces (<code>--space</code>) and dashes (<code>--dash</code>) work similarly.</li>
<li>A policy &ldquo;spaces <em>forbidden</em>&rdquo; translates to the option <code>--space 0</code>.
  Again, other character classes behave similarly.</li>
<li>A policy &ldquo;no character may appear <var>n</var> times (or more) in a row&rdquo; translates to the option <code>-<span/>-repeat (<var>n</var> − 1)</code>, for any <var>n</var> &gt; 1.
  In particular, <code>--repeat 1</code> means no character may be immediately repeated.
  (See the mnemonic below.)</li>
<li>A policy &ldquo;between <var>n</var> and <var>m</var> characters long&rdquo; translates to <code>-<span/>-length <var>k</var></code>, for any choice of <var>k</var> which satisfies <var>n</var> ≤ <var>k</var> ≤ <var>m</var>.
  (<code>derivepassphrase</code> does not explicitly choose <var>k</var> for you.)</li>
</ul>
<details class="info">
<summary>Mnemonic: the <code>--repeat</code> option</summary>
<p>The <code>--repeat</code> option denotes the <em>total</em> number of consecutive occurrences of the same character.
Or alternatively: if you request <code>-<span/>-repeat <var>n</var></code>, then <code>derivepassphrase</code> will <em>avoid</em> deriving any passphrase that repeats a character <em>another <var>n</var> times</em>.</p>
<p>Examples:</p>
<table>
<thead>
<tr>
<th style="text-align: left;">option</th>
<th style="text-align: left;">valid examples</th>
<th style="text-align: left;">invalid examples</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;"><code>--repeat 1</code></td>
<td style="text-align: left;"><code>abc</code>, <code>aba</code>, <code>abcabc</code></td>
<td style="text-align: left;"><code>aa</code>, <code>abba</code>, <code>ababb</code></td>
</tr>
<tr>
<td style="text-align: left;"><code>--repeat 4</code></td>
<td style="text-align: left;"><code>122333111123</code>, <code>4444</code></td>
<td style="text-align: left;"><code>55555</code>, <code>67788888999996</code></td>
</tr>
<tr>
<td style="text-align: left;"><code>--repeat 11</code></td>
<td style="text-align: left;"><code>01234567899999999999</code></td>
<td style="text-align: left;"><code>$$$$$$$$$$$$$$$$$$$$$$$</code></td>
</tr>
</tbody>
</table>
</details>
<p>For the <code>email</code> service, we choose passphrase length 12.
This leads to the command-line options <code>--length 12 --space 0 --upper 1 --lower 1 --number 1 --repeat 3</code>.
Because we are using a master passphrase, we also need the <code>-p</code> option.</p>
<div class="admonition note">
<p class="admonition-title">Note: interactive input</p>
<p>In code listings, sections enclosed in <code>[[...]]</code> signify input to the program, for you to type or paste in.</p>
<p>Also, it is normal for passphrase prompts to not &ldquo;echo&rdquo; the text you type in.</p>
</div>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>derivepassphrase<span class="w"> </span>vault<span class="w"> </span>--length<span class="w"> </span><span class="m">12</span><span class="w"> </span>--space<span class="w"> </span><span class="m">0</span><span class="w"> </span>--upper<span class="w"> </span><span class="m">1</span><span class="w"> </span>--lower<span class="w"> </span><span class="m">1</span><span class="w"> </span><span class="se">\</span>
<span class="gp">&gt; </span><span class="w">                       </span>--number<span class="w"> </span><span class="m">1</span><span class="w"> </span>--repeat<span class="w"> </span><span class="m">3</span><span class="w"> </span>-p<span class="w"> </span>email
<span class="go">Passphrase: [[I am an insecure master passphrase, but easy to type.]]</span>
<span class="go">kEFwoD=C?@+7</span>
</code></pre></div>
<p>By design, we can re-generate the same passphrase using the same input to <code>derivepassphrase</code>:</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>derivepassphrase<span class="w"> </span>vault<span class="w"> </span>--length<span class="w"> </span><span class="m">12</span><span class="w"> </span>--space<span class="w"> </span><span class="m">0</span><span class="w"> </span>--upper<span class="w"> </span><span class="m">1</span><span class="w"> </span>--lower<span class="w"> </span><span class="m">1</span><span class="w"> </span><span class="se">\</span>
<span class="gp">&gt; </span><span class="w">                       </span>--number<span class="w"> </span><span class="m">1</span><span class="w"> </span>--repeat<span class="w"> </span><span class="m">3</span><span class="w"> </span>-p<span class="w"> </span>email
<span class="go">Passphrase: [[I am an insecure master passphrase, but easy to type.]]</span>
<span class="go">kEFwoD=C?@+7</span>
</code></pre></div>
<p>We can then visit our email provider and change the passphrase to <code>kEFwoD=C?@+7</code>.</p>
<h3 id="storing-the-settings-to-disk">Storing the settings to disk<a class="headerlink" href="#storing-the-settings-to-disk" title="Permanent link">&para;</a></h3>
<p>Because it is tedious to memorize and type in the correct settings to re-generate this passphrase, <code>derivepassphrase</code> can optionally store these settings, using the <code>--config</code> option.</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>derivepassphrase<span class="w"> </span>vault<span class="w"> </span>--config<span class="w"> </span>--length<span class="w"> </span><span class="m">12</span><span class="w"> </span>--space<span class="w"> </span><span class="m">0</span><span class="w"> </span>--upper<span class="w"> </span><span class="m">1</span><span class="w"> </span>--lower<span class="w"> </span><span class="m">1</span><span class="w"> </span><span class="se">\</span>
<span class="gp">&gt; </span><span class="w">                       </span>--number<span class="w"> </span><span class="m">1</span><span class="w"> </span>--repeat<span class="w"> </span><span class="m">3</span><span class="w"> </span>email
</code></pre></div>
<div class="admonition warning">
<p class="admonition-title">Warning: <code>-p</code> and <code>--config</code></p>
<p>Do <strong>not</strong> use the <code>-p</code> and the <code>--config</code> options together to store the master passphrase!
The configuration is assumed to <em>not contain sensitive contents</em> and is <em>not encrypted</em>, so your master passphrase is then visible to <em>anyone</em> with appropriate privileges!</p>
</div>
<p>Check that the settings are stored correctly:</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>derivepassphrase<span class="w"> </span>vault<span class="w"> </span>--export<span class="w"> </span>-
<span class="go">{&quot;services&quot;: {&quot;email&quot;: {&quot;length&quot;: 12, &quot;repeat&quot;: 3, &quot;lower&quot;: 1, &quot;upper&quot;: 1, &quot;number&quot;: 1, &quot;space&quot;: 0}}}</span>
</code></pre></div>
<p>Once the settings are stored, only the service name and the master passphrase option are necessary:</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>derivepassphrase<span class="w"> </span>vault<span class="w"> </span>-p<span class="w"> </span>email
<span class="go">Passphrase: [[I am an insecure master passphrase, but easy to type.]]</span>
<span class="go">kEFwoD=C?@+7</span>
</code></pre></div>
<h2 id="setting-up-the-bank-account">Setting up the bank account<a class="headerlink" href="#setting-up-the-bank-account" title="Permanent link">&para;</a></h2>
<p>We choose the straightforward service name <code>bank</code>.
The passphrase policy leads to the command-line options <code>--length 5 --lower 0 --upper 0 --number 5 --space 0 --dash 0 --symbol 0</code>.</p>
<p>The additional one-time password is generated by the hardware token, and therefore out of the scope for <code>derivepassphrase</code>.</p>
<p>The rest is similar to the <code>email</code> account: we configure our stored settings, generate the passphrase, and request the bank change the account passphrase to match the generated passphrase.</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>derivepassphrase<span class="w"> </span>vault<span class="w"> </span>--config<span class="w"> </span>--length<span class="w"> </span><span class="m">5</span><span class="w"> </span>--lower<span class="w"> </span><span class="m">0</span><span class="w"> </span>--upper<span class="w"> </span><span class="m">0</span><span class="w"> </span>--number<span class="w"> </span><span class="m">5</span><span class="w"> </span><span class="se">\</span>
<span class="gp">&gt; </span><span class="w">                       </span>--space<span class="w"> </span><span class="m">0</span><span class="w"> </span>--dash<span class="w"> </span><span class="m">0</span><span class="w"> </span>--symbol<span class="w"> </span><span class="m">0</span><span class="w"> </span>bank
<span class="gp">$ </span>derivepassphrase<span class="w"> </span>vault<span class="w"> </span>-p<span class="w"> </span>bank
<span class="go">Passphrase: [[I am an insecure master passphrase, but easy to type.]]</span>
<span class="go">98517</span>
</code></pre></div>
<h2 id="setting-up-the-work-account">Setting up the work account<a class="headerlink" href="#setting-up-the-work-account" title="Permanent link">&para;</a></h2>
<p>We first take care of the first two constraints (passphrase length and permitted/required characters), then deal with the passphrase change/reuse aspects afterwards.
Again, we start with the straightforward service name <code>work</code>, we choose &ldquo;upper case letters&rdquo; to fulfill the &ldquo;1 letter&rdquo; requirement, and add the options <code>--length 8 --space 0 --symbol 1 --upper 1 --number 1</code>.</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>derivepassphrase<span class="w"> </span>vault<span class="w"> </span>--length<span class="w"> </span><span class="m">8</span><span class="w"> </span>--space<span class="w"> </span><span class="m">0</span><span class="w"> </span>--symbol<span class="w"> </span><span class="m">1</span><span class="w"> </span>--upper<span class="w"> </span><span class="m">1</span><span class="w"> </span>--number<span class="w"> </span><span class="m">1</span><span class="w"> </span><span class="se">\</span>
<span class="gp">&gt; </span><span class="w">                       </span>-p<span class="w"> </span>work
<span class="go">Passphrase: [[I am an insecure master passphrase, but easy to type.]]</span>
<span class="go">r?9\XQR&amp;</span>
</code></pre></div>
<p>Then we attempt to set the work passphrase to <code>r?9\XQR&amp;</code>… but our employer&rsquo;s identity management system returns an error: <code>illegal character: &amp;</code>.
What happened?</p>
<h3 id="complication-1-what-is-a-permitted-special-character">Complication 1: What is a (permitted) &ldquo;special character&rdquo;?<a class="headerlink" href="#complication-1-what-is-a-permitted-special-character" title="Permanent link">&para;</a></h3>
<p><code>derivepassphrase</code> considers the characters <code>!"#$%&amp;'()*+,./:;&lt;=&gt;?@[\]^{|}~-_'</code> to be permitted special characters.
Other service providers may permit other characters (quite rare) or fewer characters (quite common).
(Service providers may also <em>not</em> explicitly say which special characters they permit, except through trial and error.)</p>
<div class="admonition abstract">
<p class="admonition-title">Further reading</p>
<p>→ How to deal with &ldquo;supported&rdquo; and &ldquo;unsupported&rdquo; special characters (TODO)</p>
</div>
<p>For this case specifically, we restrict ourselves to the dashes as the only permitted special characters, and hope that this passes their passphrase policy.</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>derivepassphrase<span class="w"> </span>vault<span class="w"> </span>--length<span class="w"> </span><span class="m">8</span><span class="w"> </span>--space<span class="w"> </span><span class="m">0</span><span class="w"> </span>--symbol<span class="w"> </span><span class="m">0</span><span class="w"> </span>--dash<span class="w"> </span><span class="m">1</span><span class="w"> </span><span class="se">\</span>
<span class="gp">&gt; </span><span class="w">                       </span>--upper<span class="w"> </span><span class="m">1</span><span class="w"> </span>--number<span class="w"> </span><span class="m">1</span><span class="w"> </span>-p<span class="w"> </span>work
<span class="go">Passphrase: [[I am an insecure master passphrase, but easy to type.]]</span>
<span class="go">it90-HPO</span>
</code></pre></div>
<p>This works.
For now.</p>
<h3 id="complication-2-how-to-implement-passphrase-rotation">Complication 2: How to implement passphrase rotation?<a class="headerlink" href="#complication-2-how-to-implement-passphrase-rotation" title="Permanent link">&para;</a></h3>
<p><code>derivepassphrase</code> can only ever derive one passphrase per configuration, so passphrase rotation cannot be accomplished by reusing the same configuration.
So some part of the configuration&mdash;generally the service name&mdash;needs to change upon each rotation.</p>
<div class="admonition abstract">
<p class="admonition-title">Further reading</p>
<p>→ How to deal with regular passphrase rotation (TODO)</p>
</div>
<p>We choose to append a very coarse timestamp to the &ldquo;base&rdquo; service name <code>work</code>: the 4-digit year, a <code>Q</code>, and the &ldquo;quarter&rdquo; number (1, 2, 3 or 4).
As of October 2024, this leads to the final service name <code>work-2024Q4</code>.</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>derivepassphrase<span class="w"> </span>vault<span class="w"> </span>--config<span class="w"> </span>--length<span class="w"> </span><span class="m">8</span><span class="w"> </span>--space<span class="w"> </span><span class="m">0</span><span class="w"> </span>--symbol<span class="w"> </span><span class="m">0</span><span class="w"> </span>--dash<span class="w"> </span><span class="m">1</span><span class="w"> </span><span class="se">\</span>
<span class="gp">&gt; </span><span class="w">                       </span>--upper<span class="w"> </span><span class="m">1</span><span class="w"> </span>--number<span class="w"> </span><span class="m">1</span><span class="w"> </span>work-2024Q4
<span class="gp">$ </span>derivepassphrase<span class="w"> </span>vault<span class="w"> </span>-p<span class="w"> </span>work-2024Q4
<span class="go">Passphrase: [[I am an insecure master passphrase, but easy to type.]]</span>
<span class="go">-P268G0A</span>
</code></pre></div>
<h2 id="summary">Summary<a class="headerlink" href="#summary" title="Permanent link">&para;</a></h2>
<p>We have installed <code>derivepassphrase</code> and set up three accounts for use with the <code>vault</code> passphrase derivation scheme, and the master passphrase <code>I am an insecure master passphrase, but easy to type.</code>.
Our configuration should look like this:</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>derivepassphrase<span class="w"> </span>vault<span class="w"> </span>--export<span class="w"> </span>-
<span class="go">{&quot;services&quot;: {&quot;email&quot;: {&quot;length&quot;: 12, &quot;repeat&quot;: 3, &quot;lower&quot;: 1, &quot;upper&quot;: 1, &quot;number&quot;: 1, &quot;space&quot;: 0}, &quot;bank&quot;: {&quot;length&quot;: 5, &quot;lower&quot;: 0, &quot;upper&quot;: 0, &quot;number&quot;: 5, &quot;space&quot;: 0, &quot;dash&quot;: 0, &quot;symbol&quot;: 0}, &quot;work-2024Q4&quot;: {&quot;length&quot;: 8, &quot;upper&quot;: 1, &quot;number&quot;: 1, &quot;space&quot;: 0, &quot;dash&quot;: 1, &quot;symbol&quot;: 0}}}</span>
</code></pre></div>
<p>We should also get the following output when asking for those passphrases again:</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>derivepassphrase<span class="w"> </span>vault<span class="w"> </span>-p<span class="w"> </span>email
<span class="go">Passphrase: [[I am an insecure master passphrase, but easy to type.]]</span>
<span class="go">kEFwoD=C?@+7</span>
<span class="gp">$ </span>derivepassphrase<span class="w"> </span>vault<span class="w"> </span>-p<span class="w"> </span>bank
<span class="go">Passphrase: [[I am an insecure master passphrase, but easy to type.]]</span>
<span class="go">98517</span>
<span class="gp">$ </span>derivepassphrase<span class="w"> </span>vault<span class="w"> </span>-p<span class="w"> </span>work-2024Q4
<span class="go">Passphrase: [[I am an insecure master passphrase, but easy to type.]]</span>
<span class="go">-P268G0A</span>
</code></pre></div>
<p>This completes the tutorial.</p>

</article>
            </div>
          
          
        </div>
        
      </main>
      
        <footer class="md-footer">
  
    
      
      <nav class="md-footer__inner md-grid" aria-label="Footer" >
        
          
          <a href="../" class="md-footer__link md-footer__link--prev" aria-label="Previous: Tutorial overview">
            <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">
                Tutorial overview
              </div>
            </div>
          </a>
        
        
          
          <a href="../../how-tos/" class="md-footer__link md-footer__link--next" aria-label="Next: How-to overview">
            <div class="md-footer__title">
              <span class="md-footer__direction">
                Next
              </span>
              <div class="md-ellipsis">
                How-to overview
              </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 21da667f0ed6 to 0.x with MkDocs 1.6.1 and mike 2.1.3