0.x/how-tos/ssh-key/index.html (1bff169) - 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/how-tos/ssh-key/">
      
      
        <link rel="prev" href="../">
      
      
        <link rel="next" href="../../reference/">
      
      
        
      
      
      <link rel="icon" href="../../assets/images/favicon.png">
      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.6">
    
    
      
        <title>How to set up derivepassphrase vault with an SSH key - derivepassphrase</title>
      
    
    
      <link rel="stylesheet" href="../../assets/stylesheets/main.484c7ddc.min.css">

</a>
    </li>

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

</a>
      </li>

<li class="md-tabs__item md-tabs__item--active">
        <a href="../" 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="../../explanation/" class="md-tabs__link">
          
  
  
    
  
  Design & Background

</a>
      </li>

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

</a>
      </li>

<li class="md-tabs__item">
        <a href="../../wishlist/" class="md-tabs__link">
          
  
  
    
  
  Wishlist

</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://git.schokokeks.org/derivepassphrase.git" 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.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"/></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" >
        
          
          <div class="md-nav__link md-nav__container">
            <a href="../../tutorials/" 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="0">
                <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="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">
    
  
    Setting up derivepassphrase vault for three accounts, with a master passphrase

</span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../../tutorials/basic-setup-ssh-key/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    
  
    Using a master SSH key with derivepassphrase vault on existing accounts

</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">
    
  
    How-Tos

</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>
            
  
    How-Tos

</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">
    
  
    How to set up derivepassphrase vault with an SSH key

</span>

<span class="md-nav__icon md-icon"></span>
        </label>
      
      <a href="./" class="md-nav__link md-nav__link--active">
        
  
  
  <span class="md-ellipsis">
    
  
    How to set up derivepassphrase vault with an SSH key

</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="#prerequisites" class="md-nav__link">
    <span class="md-ellipsis">
      
        Prerequisites
      
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#configuring-derivepassphrase-vault-to-use-an-ssh-key" class="md-nav__link">
    <span class="md-ellipsis">
      
        Configuring derivepassphrase vault to use an SSH key
      
    </span>
  </a>
  
</li>
      
    </ul>
  
</nav>
      
    </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 md-nav__item--nested">
      
        
        
        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5" >
        
          
          <div class="md-nav__link md-nav__container">
            <a href="../../explanation/" class="md-nav__link ">
              
  
  
  <span class="md-ellipsis">
    
  
    Design & Background

</span>

</a>
            
              
              <label class="md-nav__link " for="__nav_5" id="__nav_5_label" tabindex="0">
                <span class="md-nav__icon md-icon"></span>
              </label>
            
          </div>
        
        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false">
          <label class="md-nav__title" for="__nav_5">
            <span class="md-nav__icon md-icon"></span>
            
  
    Design & Background

</label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
            
              
                
  
  
  
  
    <li class="md-nav__item">
      <a href="../../explanation/faq-altered-versions/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    
  
    "altered versions" license requirement

</span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../../explanation/faq-vault-interchangable-passphrases/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    
  
    "interchangable passphrases" in 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_6" >
        
          
          <label class="md-nav__link" for="__nav_6" id="__nav_6_label" tabindex="0">
            
  
  
  <span class="md-ellipsis">
    
  
    Changelog

</span>

<span class="md-nav__icon md-icon"></span>
          </label>
        
        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_6_label" aria-expanded="false">
          <label class="md-nav__title" for="__nav_6">
            <span class="md-nav__icon md-icon"></span>
            
  
    Changelog

</label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
                
  
  
  
  
    <li class="md-nav__item">
      <a href="../../changelog/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    
  
    Changelog

</span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../../upgrade-notes/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    
  
    Upgrade notes

</span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../../pycompatibility/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    
  
    Python compatibility

</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_7" >
        
          
          <div class="md-nav__link md-nav__container">
            <a href="../../wishlist/" class="md-nav__link ">
              
  
  
  <span class="md-ellipsis">
    
  
    Wishlist

</span>

</a>
            
          </div>
        
        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_7_label" aria-expanded="false">
          <label class="md-nav__title" for="__nav_7">
            <span class="md-nav__icon md-icon"></span>
            
  
    Wishlist

</label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
            
          </ul>
        </nav>
      
    </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="how-to-set-up-derivepassphrase-vault-with-an-ssh-key">How to set up <code>derivepassphrase vault</code> with an SSH key<a class="headerlink" href="#how-to-set-up-derivepassphrase-vault-with-an-ssh-key" title="Permanent link">&para;</a></h1>
<div class="admonition abstract">
<p class="admonition-title">See also</p>
<p>→ Tradeoffs between a master passphrase and a master SSH key (TODO)</p>
</div>
<h2 id="prerequisites">Prerequisites<a class="headerlink" href="#prerequisites" title="Permanent link">&para;</a></h2>
<div class="admonition abstract">
<p class="admonition-title">Further reading</p>
<p>→ Full technical details: <a href="../../reference/prerequisites-ssh-key/">Prerequisites for using <code>derivepassphrase
vault</code> with an SSH key</a></p>
</div>
<ol>
<li>A running SSH agent; typically provided by OpenSSH or PuTTY.</li>
<li>A Python installation that can talk to the SSH agent.</li>
<li>A supported SSH key; typically an RSA, Ed25519 or Ed448 key.</li>
</ol>
<h2 id="configuring-derivepassphrase-vault-to-use-an-ssh-key">Configuring <code>derivepassphrase vault</code> to use an SSH key<a class="headerlink" href="#configuring-derivepassphrase-vault-to-use-an-ssh-key" title="Permanent link">&para;</a></h2>
<p>Assuming the prerequisites are satisfied, ensure that the SSH agent is
running, the SSH key is loaded into the agent, and that
<code>derivepassphrase</code> can <i>discover</i> the agent:</p>
<div class="admonition info">
<p class="admonition-title">Making the SSH agent discoverable</p>
<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">on UNIX</label><label for="__tabbed_1_2">on Windows</label></div>
<div class="tabbed-content">
<div class="tabbed-block">
<p>…the <code>SSH_AUTH_SOCK</code> environment variable must be correctly set up.</p>
</div>
<div class="tabbed-block">
<p>…by default, the <code>SSH_AUTH_SOCK</code> environment variable must be
correctly set up.</p>
<p>Alternatively, <code>derivepassphrase</code> can be explicitly configured to
connect to OpenSSH or Pageant (PuTTY) directly, without consulting
<code>SSH_AUTH_SOCK</code>.
In that case, the respective agent must be running.</p>
</div>
</div>
</div>
</div>
<p>The exact commands depend on the SSH agent in use.</p>
<div class="admonition info">
<p class="admonition-title">Setup commands</p>
<div class="tabbed-set tabbed-alternate" data-tabs="2:3"><input checked="checked" id="__tabbed_2_1" name="__tabbed_2" type="radio" /><input id="__tabbed_2_2" name="__tabbed_2" type="radio" /><input id="__tabbed_2_3" name="__tabbed_2" type="radio" /><div class="tabbed-labels"><label for="__tabbed_2_1">OpenSSH</label><label for="__tabbed_2_2">PuTTY</label><label for="__tabbed_2_3">GnuPG</label></div>
<div class="tabbed-content">
<div class="tabbed-block">
<div class="tabbed-set tabbed-alternate" data-tabs="3:2"><input checked="checked" id="__tabbed_3_1" name="__tabbed_3" type="radio" /><input id="__tabbed_3_2" name="__tabbed_3" type="radio" /><div class="tabbed-labels"><label for="__tabbed_3_1">on UNIX</label><label for="__tabbed_3_2">on Windows</label></div>
<div class="tabbed-content">
<div class="tabbed-block">
<div class="highlight"><span class="filename">Typical setup commands: starting the agent and setting up SSH_AUTH_SOCK</span><pre><span></span><code><span class="gp">$ </span><span class="nb">eval</span><span class="w"> </span><span class="sb">`</span>ssh-agent<span class="w"> </span>-s<span class="sb">`</span>
<span class="go">Agent pid 12345</span>
</code></pre></div>
<p>(The process ID emitted above is helpful for signalling the agent
later, e.g. for termination.)</p>
<div class="highlight"><span class="filename">Typical setup commands: loading the key into the agent, with 900s timeout and requiring confirmation</span><pre><span></span><code><span class="gp">$ </span>ssh-add<span class="w"> </span>-t<span class="w"> </span><span class="m">900</span><span class="w"> </span>-c<span class="w"> </span>~/.ssh/my-vault-ed25519-key
<span class="go">Enter passphrase for /home/user/.ssh/my-vault-ed25519-key (will confirm each use): </span>
<span class="go">Identity added: /home/user/.ssh/my-vault-ed25519-key (vault key)</span>
<span class="go">Lifetime set to 900 seconds</span>
<span class="go">The user must confirm each use of the key</span>
</code></pre></div>
<p>(Your key filename and key comment will likely differ.)</p>
</div>
<div class="tabbed-block">
<p>(<a href="../../reference/prerequisites-ssh-key/#agent-specific-notes">Using OpenSSH on Windows is possible, but currently <em>not
recommended</em>; we recommend Pageant
instead.</a>)</p>
<p>The agent is started as a system service.
This only needs to be set up once.</p>
<p><small>(<a href="https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_keymanagement#user-key-generation">Source: OpenSSH-on-Windows
documentation</a>.)</small></p>
<div class="highlight"><span class="filename">Typical setup commands (PowerShell, as Administrator): starting the agent</span><pre><span></span><code><span class="gp">PS&gt; </span><span class="nb">Get-Service</span> <span class="n">ssh-agent</span> <span class="p">|</span> <span class="nb">Set-Service</span> <span class="n">-StartupType</span> <span class="n">Automatic</span>
<span class="gp">PS&gt; </span><span class="nb">Start-Service</span> <span class="n">ssh-agent</span>
</code></pre></div>
<p>Load the keys into the agent.
This only needs to be done once.
The agent stores the key material in a reusable, per-user
Windows security context.
Unlike on UNIX, the Windows port of OpenSSH does not support key
timeouts or key usage confirmation prompts.</p>
<div class="highlight"><span class="filename">Further setup commands (Powershell, as User): loading the key into the agent</span><pre><span></span><code><span class="gp">PS&gt; </span><span class="n">ssh-add</span> <span class="s2">&quot;C:\Users\YourUsernameHere\Documents\my-vault-ed25519-key&quot;</span>
<span class="go">Enter passphrase for C:\Users\YourUsernameHere\Documents\my-vault-ed25519-key:</span>
<span class="go">Identity added: C:\Users\YourUsernameHere\Documents\my-vault-ed25519-key (vault key)</span>
</code></pre></div>
<p>(Your key filename and key comment will likely differ.)</p>
<p>Finally, inform <code>derivepassphrase</code> about the OpenSSH agent&rsquo;s
address:</p>
<div class="tabbed-set tabbed-alternate" data-tabs="4:2"><input checked="checked" id="__tabbed_4_1" name="__tabbed_4" type="radio" /><input id="__tabbed_4_2" name="__tabbed_4" type="radio" /><div class="tabbed-labels"><label for="__tabbed_4_1"><code>openssh_on_windows</code> socket provider</label><label for="__tabbed_4_2"><code>SSH_AUTH_SOCK</code> on Windows (not recommended)</label></div>
<div class="tabbed-content">
<div class="tabbed-block">
<p>Edit the file
<code>C:\&#x200b;Users\&#x200b;&lt;username&gt;&#x200b;AppData\&#x200b;Roaming\&#x200b;derivepassphrase\&#x200b;config.toml</code>
and set the key <code>vault.ssh-agent-socket-provider</code> to
<code>openssh_on_windows</code>:</p>
<div class="highlight"><span class="filename">config.toml</span><pre><span></span><code><span class="k">[vault]</span>
<span class="n">ssh-agent-socket-provider</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">&quot;openssh_on_windows&quot;</span>
</code></pre></div>
</div>
<div class="tabbed-block">
<p>(The &ldquo;native&rdquo; SSH agent socket provider must be in use.)</p>
<div class="highlight"><span class="filename">Further setup commands (Powershell, as User): setting SSH_AUTH_SOCK</span><pre><span></span><code><span class="gp">PS&gt; </span><span class="nv">$env:SSH_AUTH_SOCK</span> <span class="p">=</span> <span class="s2">&quot;\\.\pipe\openssh-ssh-agent&quot;</span>
</code></pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="tabbed-block">
<div class="tabbed-set tabbed-alternate" data-tabs="5:2"><input checked="checked" id="__tabbed_5_1" name="__tabbed_5" type="radio" /><input id="__tabbed_5_2" name="__tabbed_5" type="radio" /><div class="tabbed-labels"><label for="__tabbed_5_1">on Windows</label><label for="__tabbed_5_2">on UNIX</label></div>
<div class="tabbed-content">
<div class="tabbed-block">
<div style="float: right;">
<p><figure markdown>
<img alt="A CRT monitor wearing a spy hat." loading="lazy" src="../../tutorials/pageant.svg" width="96" />
<figcaption>
The <code>pageant</code> icon
</figcaption>
</figure></p>
</div>
<p>Start Pageant; this adds the Pageant icon to the Windows task
bar.
Then add the key via the right-click context menu, &ldquo;Add key&rdquo; or
&ldquo;Add key (encrypted)&rdquo;.</p>
<p>Adding the key via &ldquo;Add key (encrypted)&rdquo; makes the key material
manually &ldquo;lockable&rdquo; and &ldquo;unlockable&rdquo; by decrypting and
re-encrypting it, meaning that the key cannot be used by
malicious clients while encrypted.
This can be used to partially alleviate the lack of support for
the &ldquo;key timeout&rdquo; and &ldquo;confirm on use&rdquo; constraint.
The &ldquo;Add key (encrypted)&rdquo; mode is thus <em>recommended</em>.</p>
<p>Finally, inform <code>derivepassphrase</code> about Pageant&rsquo;s address:</p>
<div class="tabbed-set tabbed-alternate" data-tabs="6:2"><input checked="checked" id="__tabbed_6_1" name="__tabbed_6" type="radio" /><input id="__tabbed_6_2" name="__tabbed_6" type="radio" /><div class="tabbed-labels"><label for="__tabbed_6_1"><code>pageant_on_windows</code> socket provider</label><label for="__tabbed_6_2"><code>SSH_AUTH_SOCK</code> on Windows (not recommended)</label></div>
<div class="tabbed-content">
<div class="tabbed-block">
<p>Edit the file
<code>C:\&#x200b;Users\&#x200b;&lt;username&gt;&#x200b;AppData\&#x200b;Roaming\&#x200b;derivepassphrase\&#x200b;config.toml</code>
and set the key <code>vault.ssh-agent-socket-provider</code> to
<code>pageant_on_windows</code>:</p>
<div class="highlight"><span class="filename">config.toml</span><pre><span></span><code><span class="k">[vault]</span>
<span class="n">ssh-agent-socket-provider</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">&quot;pageant_on_windows&quot;</span>
</code></pre></div>
</div>
<div class="tabbed-block">
<p>(The &ldquo;native&rdquo; SSH agent socket provider must be in use.)</p>
<p>Pageant&rsquo;s address is unfortunately not fixed.
To get Pageant to write out its socket address on startup,
start it with the <code>--openssh-config &lt;filename&gt;</code> option to
write an OpenSSH-compatible configuration snippet to
<code>&lt;filename&gt;</code>, which includes the address.</p>
<div class="highlight"><span class="filename">Further setup commands (Powershell, as User): setting SSH_AUTH_SOCK</span><pre><span></span><code><span class="gp">PS&gt; </span><span class="n">pageant</span> <span class="p">-</span><span class="n">-openssh-config</span> <span class="n">file</span><span class="p">.</span><span class="n">conf</span>
<span class="gp">PS&gt; </span>
<span class="gp">PS&gt; </span><span class="c"># Now read file.conf to learn the address; it looks like</span>
<span class="gp">PS&gt; </span><span class="c"># &quot;\\.\pipe\pageant.&lt;username&gt;.0123456789abcdef...&quot;</span>
<span class="gp">PS&gt;</span>
<span class="gp">PS&gt; </span><span class="nv">$env:SSH_AUTH_SOCK</span> <span class="p">=</span> <span class="s2">&quot;\\.\pipe\pageant.YourUsernameHere.0123456789deadbeef...&quot;</span>
</code></pre></div>
</div>
</div>
</div>
</div>
<div class="tabbed-block">
<div class="highlight"><span class="filename">Typical setup commands: starting the agent and loading the key</span><pre><span></span><code><span class="gp">$ </span><span class="nb">eval</span><span class="w"> </span><span class="sb">`</span>pageant<span class="w"> </span>-T<span class="w"> </span>~/.ssh/my-vault-ed25519-key.ppk<span class="sb">`</span>
<span class="go">Enter passphrase to load key &#39;vault key&#39;: </span>
</code></pre></div>
<p>(Your key filename and key comment will likely differ.
The agent should automatically shut down once this terminal
session is over.)</p>
</div>
</div>
</div>
</div>
<div class="tabbed-block">
<div class="tabbed-set tabbed-alternate" data-tabs="7:2"><input checked="checked" id="__tabbed_7_1" name="__tabbed_7" type="radio" /><input id="__tabbed_7_2" name="__tabbed_7" type="radio" /><div class="tabbed-labels"><label for="__tabbed_7_1">on UNIX</label><label for="__tabbed_7_2">on Windows</label></div>
<div class="tabbed-content">
<div class="tabbed-block">
<div class="highlight"><span class="filename">Typical setup commands: enabling SSH agent support in GnuPG</span><pre><span></span><code><span class="gp">$ </span><span class="c1"># This is equivalent to passing --enable-ssh-support upon agent</span>
<span class="gp">$ </span><span class="c1"># startup.</span>
<span class="gp">$ </span><span class="nb">echo</span><span class="w"> </span>enable-ssh-support:0:1<span class="w"> </span><span class="p">|</span><span class="w"> </span>gpgconf<span class="w"> </span>--change-options<span class="w"> </span>gpg-agent
<span class="gp">$ </span><span class="c1"># Then export the SSH_AUTH_SOCK environment variable appropriately.</span>
<span class="gp">$ </span><span class="nb">export</span><span class="w"> </span><span class="nv">SSH_AUTH_SOCK</span><span class="o">=</span><span class="s2">&quot;</span><span class="k">$(</span>gpgconf<span class="w"> </span>--list-dirs<span class="w"> </span>agent-ssh-socket<span class="k">)</span><span class="s2">&quot;</span>
</code></pre></div>
<p>(Loading native SSH keys into <code>gpg-agent</code> requires
a separate SSH agent client such as OpenSSH; see the
<a href="../../reference/prerequisites-ssh-key/#agent-specific-notes">agent-specific notes in the
prerequisites</a>.)</p>
<div class="highlight"><span class="filename">Typical setup commands: loading the key into the agent with the OpenSSH tools</span><pre><span></span><code><span class="gp">$ </span>ssh-add<span class="w"> </span>-c<span class="w"> </span>~/.ssh/my-vault-ed25519-key
<span class="go">Enter passphrase for /home/user/.ssh/my-vault-ed25519-key (will confirm each use): </span>
<span class="go">Identity added: /home/user/.ssh/my-vault-ed25519-key (vault key)</span>
<span class="go">The user must confirm each use of the key</span>
</code></pre></div>
<p>(Your key filename and key comment may differ.)</p>
</div>
<div class="tabbed-block">
<p>Edit the file <code>gpg-agent.conf</code> in the GnuPG home directory to
contain the line <code>enable-win32-openssh-support</code>, which is
equivalent to passing <code>--enable-win32-openssh-support</code> upon
agent startup.
This causes <code>gpg-agent</code> to masquerade as OpenSSH`s agent.</p>
<p>Then, inform <code>derivepassphrase</code> about the agent&rsquo;s address,
i.e., of the OpenSSH agent&rsquo;s socket address:</p>
<div class="tabbed-set tabbed-alternate" data-tabs="8:2"><input checked="checked" id="__tabbed_8_1" name="__tabbed_8" type="radio" /><input id="__tabbed_8_2" name="__tabbed_8" type="radio" /><div class="tabbed-labels"><label for="__tabbed_8_1"><code>openssh_on_windows</code> socket provider</label><label for="__tabbed_8_2"><code>SSH_AUTH_SOCK</code> on Windows (not recommended)</label></div>
<div class="tabbed-content">
<div class="tabbed-block">
<p>Edit the file
<code>C:\&#x200b;Users\&#x200b;&lt;username&gt;&#x200b;AppData\&#x200b;Roaming\&#x200b;derivepassphrase\&#x200b;config.toml</code>
and set the key <code>vault.ssh-agent-socket-provider</code> to
<code>openssh_on_windows</code>:</p>
<div class="highlight"><span class="filename">config.toml</span><pre><span></span><code><span class="k">[vault]</span>
<span class="n">ssh-agent-socket-provider</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">&quot;openssh_on_windows&quot;</span>
</code></pre></div>
</div>
<div class="tabbed-block">
<p>(The &ldquo;native&rdquo; SSH agent socket provider must be in use.)</p>
<div class="highlight"><span class="filename">Further setup commands (Powershell, as User): setting SSH_AUTH_SOCK</span><pre><span></span><code><span class="gp">PS&gt; </span><span class="nv">$env:SSH_AUTH_SOCK</span> <span class="p">=</span> <span class="s2">&quot;\\.\pipe\openssh-ssh-agent&quot;</span>
</code></pre></div>
</div>
</div>
</div>
<p>(Loading native SSH keys into <code>gpg-agent</code> requires
a separate SSH agent client such as OpenSSH; see the
<a href="../../reference/prerequisites-ssh-key/#agent-specific-notes">agent-specific notes in the
prerequisites</a>.)</p>
<div class="highlight"><span class="filename">Typical setup commands (PowerShell): loading the key into the agent with the OpenSSH tools</span><pre><span></span><code><span class="gp">$ </span>ssh-add<span class="w"> </span><span class="s2">&quot;C:\Users\YourUsernameHere\Documents\my-vault-ed25519-key&quot;</span>
<span class="go">Enter passphrase for C:\Users\YourUsernameHere\Documents\my-vault-ed25519-key (will confirm each use): </span>
<span class="go">Identity added: C:\Users\YourUsernameHere\Documents\my-vault-ed25519-key (vault key)</span>
<span class="go">The user must confirm each use of the key</span>
</code></pre></div>
<p>(Your key filename and key comment may differ.)</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<p>Next, configure <code>derivepassphrase vault</code> to use the loaded SSH key.</p>
<div class="admonition quote">
<div class="tabbed-set tabbed-alternate" data-tabs="9:2"><input checked="checked" id="__tabbed_9_1" name="__tabbed_9" type="radio" /><input id="__tabbed_9_2" name="__tabbed_9" type="radio" /><div class="tabbed-labels"><label for="__tabbed_9_1">global key</label><label for="__tabbed_9_2">key specifically for <var>SERVICE</var></label></div>
<div class="tabbed-content">
<div class="tabbed-block">
<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>-k
<span class="go">Suitable SSH keys:</span>
<span class="go">[1] ssh-rsa ...feXycsvJZ2uaYRjMdZeJGNAnHLUGLkBscw5aI8=  test key without passphrase</span>
<span class="go">[2] ssh-ed448 ...BQ72ZgtPMckdzabiz7JbM/b0JzcRzGLMsbwA=  test key without passphrase</span>
<span class="go">[3] ssh-ed25519 ...gJIXw//Mkhv5MEwidwcakUGCekJD/vCEml2  test key without passphrase</span>
<span class="go">Your selection? (1-3, leave empty to abort): 3</span>
</code></pre></div>
<p>(The prompt text will be &ldquo;Use this key?&rdquo; instead if there is only one
suitable key.)</p>
<p>Now <code>derivepassphrase vault</code> will automatically use the configured
key globally, even without the <code>-k</code>/<code>--key</code> option.</p>
</div>
<div class="tabbed-block">
<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>-k<span class="w"> </span>SERVICE
<span class="go">Suitable SSH keys:</span>
<span class="go">[1] ssh-rsa ...feXycsvJZ2uaYRjMdZeJGNAnHLUGLkBscw5aI8=  test key without passphrase</span>
<span class="go">[2] ssh-ed448 ...BQ72ZgtPMckdzabiz7JbM/b0JzcRzGLMsbwA=  test key without passphrase</span>
<span class="go">[3] ssh-ed25519 ...gJIXw//Mkhv5MEwidwcakUGCekJD/vCEml2  test key without passphrase</span>
<span class="go">Your selection? (1-3, leave empty to abort): 3</span>
</code></pre></div>
<p>(The prompt text will be &ldquo;Use this key?&rdquo; instead if there is only one
suitable key.)</p>
<p>Now <code>derivepassphrase vault</code> will automatically use the configured
key for <var>SERVICE</var>, even without the <code>-k</code>/<code>--key</code> option.</p>
</div>
</div>
</div>
</div>
<div class="admonition abstract">
<p class="admonition-title">Further reading</p>
<p>→ Tradeoffs between a master passphrase and a master SSH key,
section &ldquo;Should I use one master SSH key, or many keys?&rdquo; (TODO)</p>
</div>
<aside>
<details class="abstract">
<summary>Image credits</summary>
<ul>
<li>The <code>pageant</code> logo is part of the PuTTY software package, generated from source files contained within.
  <a href="https://git.tartarus.org/?p=simon/putty.git;a=blob;f=LICENCE;h=091556577ce55d3502f121460668c5495de91baa;hb=refs/tags/0.83" title="License for the PuTTY software suite (and icons)">License</a></li>
</ul>
</details>
</aside>

</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: How-to 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">
                How-to overview
              </div>
            </div>
          </a>
        
        
          
          <a href="../../reference/" class="md-footer__link md-footer__link--next" aria-label="Next: Reference overview">
            <div class="md-footer__title">
              <span class="md-footer__direction">
                Next
              </span>
              <div class="md-ellipsis">
                Reference 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; 2026 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 4d028b5c74e3 to 0.x with MkDocs 1.6.1 and mike 2.1.4