/usr/share/doc/monkeysign-doc/html/usage.html is in monkeysign-doc 2.2.3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 | <!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Usage — Monkeysign 2.2.3 documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="index" title="Index"
href="genindex.html"/>
<link rel="search" title="Search" href="search.html"/>
<link rel="top" title="Monkeysign 2.2.3 documentation" href="index.html"/>
<link rel="next" title="Support" href="support.html"/>
<link rel="prev" title="Install" href="install.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="index.html" class="icon icon-home"> Monkeysign
<img src="_static/logo.simple.png" class="logo" />
</a>
<div class="version">
2.2.3
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Usage</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#monkeysign">Monkeysign</a></li>
<li class="toctree-l2"><a class="reference internal" href="#monkeyscan">Monkeyscan</a></li>
<li class="toctree-l2"><a class="reference internal" href="#sending-signed-key-material">Sending signed key material</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#using-the-system-email-software-mta">Using the system email software (MTA)</a></li>
<li class="toctree-l3"><a class="reference internal" href="#using-your-normal-email-client-mua">Using your normal email client (MUA)</a></li>
<li class="toctree-l3"><a class="reference internal" href="#using-smtp">Using SMTP</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#configuration-files">Configuration files</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="support.html">Support</a></li>
<li class="toctree-l1"><a class="reference internal" href="contributing.html">Contribute</a></li>
<li class="toctree-l1"><a class="reference internal" href="history.html">History</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="ui-mockups/index.html">UI mockups and design</a></li>
<li class="toctree-l1"><a class="reference internal" href="glossary.html">Terminology</a></li>
<li class="toctree-l1"><a class="reference internal" href="credits.html">Credits</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">Monkeysign</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> »</li>
<li>Usage</li>
<li class="wy-breadcrumbs-aside">
<a href="https://0xacab.org/monkeysphere/monkeysign/blob/HEAD/doc/usage.rst">View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="usage">
<h1>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h1>
<p>Monkeysign comes in two different interfaces: a commandline interface
named <cite>monkeysign</cite> and a graphical interface named <cite>monkeyscan</cite>.</p>
<p>Monkeysign creates a temporary keyring to sign keys, and then
encrypts and sends the signature by email to the owner of the key.
This makes possible to verify that the holder of the private key (used to
decrypt the signature) has also access to the mailbox mentioned in the key.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Make sure you have your email credentials in hand and read
the <a class="reference internal" href="#email-config"><span class="std std-ref">Sending signed key material</span></a> section before starting, as
Monkeysign may not know, by default, how to send email.</p>
</div>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">If you have problems using Monkeysign, please do report
issues and bugs about it, it’s a great way of contributing!
We also welcome documentation, translation and patches, see
<a class="reference internal" href="contributing.html"><span class="doc">Contribute</span></a> for more information.</p>
</div>
<div class="section" id="monkeysign">
<h2>Monkeysign<a class="headerlink" href="#monkeysign" title="Permalink to this headline">¶</a></h2>
<p>The commandline interface should provide you with a complete help file
when called with <code class="docutils literal"><span class="pre">--help</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">monkeysign</span> <span class="o">--</span><span class="n">help</span>
</pre></div>
</div>
<p>For example, to sign the Monkeysign test key:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">monkeysign</span> <span class="mi">3</span><span class="n">F94</span> <span class="mi">240</span><span class="n">C</span> <span class="mi">918</span><span class="n">E</span> <span class="mi">6359</span> <span class="mb">0B0</span><span class="mi">4</span> <span class="mi">152</span><span class="n">E</span> <span class="mf">86E4</span> <span class="n">E70A</span> <span class="mi">96</span><span class="n">F4</span> <span class="mi">7</span><span class="n">C6A</span>
</pre></div>
</div>
<p>This will fetch the key from your keyring (or a keyserver) and sign it
in a temporary keyring, then encrypt the signature and send it in an
email to the owner of the key. Emails can be sent in different ways,
documented in <a class="reference internal" href="#email-config"><span class="std std-ref">Sending signed key material</span></a>.</p>
<p>If the wrong secret key is chosen to sign the key, you can override it
with the <code class="docutils literal"><span class="pre">--user</span></code> option.</p>
<div class="admonition caution">
<p class="first admonition-title">Caution</p>
<p class="last">It is important to use Monkeysign with the fingerprint,
and <em>not with the key id</em>, specially when using it
through the Tor network, as a key id can be duplicated
easily, unlike fingerprints.</p>
</div>
</div>
<div class="section" id="monkeyscan">
<h2>Monkeyscan<a class="headerlink" href="#monkeyscan" title="Permalink to this headline">¶</a></h2>
<p>The graphical interface (<cite>GUI</cite>) should be self-explanatory, it should
be in your regular application menus, or you can call start it form
the commandline with:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">monkeyscan</span>
</pre></div>
</div>
<p>The GUI will show you a <a class="reference internal" href="glossary.html#term-bar-code"><span class="xref std std-term">bar code</span></a> representing the fingerprint
of what Monkeysign thinks is your primary key. You can change that in
the <cite>Identity</cite> menu, or by customizing the <code class="docutils literal"><span class="pre">default-key</span></code> parameter
in your <code class="docutils literal"><span class="pre">gpg.conf</span></code> file.</p>
<p>On the left side, you should see the output of your camera. You can
change cameras (if you have more than one) in the <cite>Video device</cite> menu,
where you can also turn off the camera altogether.</p>
<p>To exchange fingerprints, you should point the camera at another
user’s bar code. Monkeysign will detect that user’s key fingerprint,
fetch the key over the network from keyservers, then ask you for
confirmation before signing and sending the email, just like the
command line interface. See <a class="reference internal" href="#email-config"><span class="std std-ref">Sending signed key material</span></a> for more information
about how email is sent in Monkeysign in general.</p>
<p>There is a very crude preferences window available in the <cite>Edit</cite>
menu. There is work underway to improve it (see <a class="reference external" href="https://0xacab.org/monkeysphere/monkeysign/issues/41">0xACAB issue #41</a>), but it
should allow you to create a configuration file with your personal
settings. See <a class="reference internal" href="#configuration-files"><span class="std std-ref">Configuration files</span></a> for more information about
this as well.</p>
</div>
<div class="section" id="sending-signed-key-material">
<span id="email-config"></span><h2>Sending signed key material<a class="headerlink" href="#sending-signed-key-material" title="Permalink to this headline">¶</a></h2>
<p>Monkeysign will attempt to send the signed key by email, unless the
<code class="docutils literal"><span class="pre">--no-mail</span></code> argument is specified. In this case, the encrypted key
material is shown on the terminal and can then be copy-pasted in the
medium of your choice. This is useful, for example, if you use a
web email client like Roundcube, Google Mail or similar.</p>
<p>Monkeysign supports many ways of sending emails:</p>
<ul class="simple">
<li><a class="reference internal" href="#mta"><span class="std std-ref">Using the system email software (MTA)</span></a> (e.g. sendmail or Postfix)</li>
<li><a class="reference internal" href="#mua"><span class="std std-ref">Using your normal email client (MUA)</span></a> (e.g. Thunderbird or Mutt)</li>
<li><a class="reference internal" href="#smtp"><span class="std std-ref">Using SMTP</span></a> (e.g. connecting directly to your provider)</li>
</ul>
<p>Also note that the <code class="docutils literal"><span class="pre">--tor</span></code> option affects how email will be sent,
but only when using the SMTP method, as Monkeysign has no way to
handle how your <a class="reference internal" href="glossary.html#term-mua"><span class="xref std std-term">MUA</span></a> or <a class="reference internal" href="glossary.html#term-mta"><span class="xref std std-term">MTA</span></a> will talk to the network.</p>
<div class="section" id="using-the-system-email-software-mta">
<span id="mta"></span><h3>Using the system email software (MTA)<a class="headerlink" href="#using-the-system-email-software-mta" title="Permalink to this headline">¶</a></h3>
<p>Monkeysign, by default, assumes you have a local <a class="reference internal" href="glossary.html#term-mta"><span class="xref std std-term">MTA</span></a> installed
as <code class="docutils literal"><span class="pre">sendmail</span></code>. If it is not, you can specify the path to a
<code class="docutils literal"><span class="pre">sendmail</span></code> compatible program with the <code class="docutils literal"><span class="pre">--mta</span></code> option. Such a
program should accept the complete message on standard input, and the
recipient is passed on the commandline in place of the <code class="docutils literal"><span class="pre">%(to)s</span></code>
argument.</p>
<p>Note that it is uncommon for workstations and laptops to have a
working <a class="reference internal" href="glossary.html#term-mta"><span class="xref std std-term">MTA</span></a> installed: this is more commonly done on servers,
and unless you know what you are doing, you are more likely to want to
talk to your existing email client, your <a class="reference internal" href="glossary.html#term-mua"><span class="xref std std-term">MUA</span></a>.</p>
</div>
<div class="section" id="using-your-normal-email-client-mua">
<span id="mua"></span><h3>Using your normal email client (MUA)<a class="headerlink" href="#using-your-normal-email-client-mua" title="Permalink to this headline">¶</a></h3>
<p>Therefore, to properly send email on your workstation, you may need to
tell Monkeysign how to use your regular email client, your
<a class="reference internal" href="glossary.html#term-mua"><span class="xref std std-term">MUA</span></a>. For this, you can use the <code class="docutils literal"><span class="pre">--mua</span></code> option.</p>
<p>By default, Monkeysign will try to figure out your default email
client when you use the <code class="docutils literal"><span class="pre">--mua</span></code> flag is used without argument. This
will in turn call the <code class="docutils literal"><span class="pre">xdg-email</span></code> command which automatically uses
your configured email client correctly:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">monkeysign</span> <span class="o">--</span><span class="n">mua</span> <span class="p">[</span><span class="o">...</span><span class="p">]</span>
</pre></div>
</div>
<p>Your default mail client can be modified in your desktop environment
control panel, or with the <code class="docutils literal"><span class="pre">xdg-mime</span></code> command, for example this will
set Thunderbird as your default email client:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">xdg</span><span class="o">-</span><span class="n">mime</span> <span class="n">default</span> <span class="n">thunderbird</span><span class="o">.</span><span class="n">desktop</span> <span class="n">x</span><span class="o">-</span><span class="n">scheme</span><span class="o">-</span><span class="n">handler</span><span class="o">/</span><span class="n">mailto</span>
</pre></div>
</div>
<p>You can also specify your own email client on the fly. Here are few
examples of known working configurations.</p>
<ul>
<li><p class="first">Thunderbird:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">monkeysign</span> <span class="o">--</span><span class="n">mua</span> <span class="s2">"thunderbird -compose to=</span><span class="si">%(to)s</span><span class="s2">,subject=</span><span class="si">%(subject)s</span><span class="s2">,body=</span><span class="si">%(body)s</span><span class="s2">,attachment=</span><span class="si">%(attach)s</span><span class="s2">"</span> <span class="p">[</span><span class="o">...</span><span class="p">]</span>
</pre></div>
</div>
</li>
<li><p class="first">Mutt:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">monkeysign</span> <span class="o">--</span><span class="n">mua</span> <span class="s2">"mutt -a </span><span class="si">%(attach)s</span><span class="s2"> -s </span><span class="si">%(subject)s</span><span class="s2"> -i </span><span class="si">%(body)s</span><span class="s2"> </span><span class="si">%(to)s</span><span class="s2">"</span> <span class="p">[</span><span class="o">...</span><span class="p">]</span>
</pre></div>
</div>
</li>
</ul>
<p>Finally, note that you need to confirm when you are finished writing
the actual email. This is because we cannot tell when the email is
sent, because a lot of software (especially Thunderbird) return before
the email is sent, see <a class="reference external" href="https://bugs.debian.org/677430">Debian BTS #677430</a> for more information about this
issue.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Essentially, the difference between <code class="docutils literal"><span class="pre">--mta</span></code> and <code class="docutils literal"><span class="pre">--mua</span></code>
is that the complete message is piped through the
<a class="reference internal" href="glossary.html#term-mta"><span class="xref std std-term">MTA</span></a> command whereas it is passed as an argument on
the commandline for <a class="reference internal" href="glossary.html#term-mua"><span class="xref std std-term">MUA</span></a> commands. Also, the
<code class="docutils literal"><span class="pre">--mta</span></code> command expands only the <code class="docutils literal"><span class="pre">%(to)s</span></code> parameter,
whereas the <code class="docutils literal"><span class="pre">--mua</span></code> command expands <code class="docutils literal"><span class="pre">%(attach)s</span></code>,
<code class="docutils literal"><span class="pre">%(subject)s</span></code>, <code class="docutils literal"><span class="pre">%(body)s</span></code> and <code class="docutils literal"><span class="pre">%(to)s</span></code>.</p>
<p>Note that when a <code class="docutils literal"><span class="pre">--mua</span></code> is used, only the key material is
encrypted: the body of the email is sent in the clear. This
is because Monkeysign cannot control how the attachment
layout in the <a class="reference internal" href="glossary.html#term-mua"><span class="xref std std-term">MUA</span></a> in a standard way.</p>
<p class="last">Furthermore, it may be more difficult for the end-user to
import the key when it was sent with a <a class="reference internal" href="glossary.html#term-mua"><span class="xref std std-term">MUA</span></a>, as the
recipient’s own <a class="reference internal" href="glossary.html#term-mua"><span class="xref std std-term">MUA</span></a> may not know how to both decrypt
<em>and</em> import the key at the same time. The <a class="reference internal" href="glossary.html#term-mta"><span class="xref std std-term">MTA</span></a>
method doesn’t have this problem because of MIME
encapsulation. See also <a class="reference external" href="https://0xacab.org/monkeysphere/monkeysign/issues/7">0xACAB issue #7</a> for a broader technical
discussion about the <code class="docutils literal"><span class="pre">--mua</span></code> implementation.</p>
</div>
</div>
<div class="section" id="using-smtp">
<span id="smtp"></span><h3>Using SMTP<a class="headerlink" href="#using-smtp" title="Permalink to this headline">¶</a></h3>
<p>Note that you can also send email using your provider’s SMTP server
directly, turning Monkeysign into a <a class="reference internal" href="glossary.html#term-mua"><span class="xref std std-term">MUA</span></a> itself. For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">monkeysign</span> <span class="o">--</span><span class="n">smtp</span><span class="o">=</span><span class="n">mail</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="p">:</span><span class="mi">587</span> <span class="o">--</span><span class="n">smtpuser</span><span class="o">=</span><span class="n">john</span> <span class="p">[</span><span class="n">fingerprint</span> <span class="n">of</span> <span class="n">OpenPGP</span> <span class="n">key</span> <span class="n">to</span> <span class="n">sign</span><span class="p">]</span>
</pre></div>
</div>
<p>In the above, Monkeysign will attempt to connect to the
<code class="docutils literal"><span class="pre">mail.example.com</span></code> SMTP server over the submission port (<code class="docutils literal"><span class="pre">587</span></code>),
attempt to upgrade the connection securely (using <code class="docutils literal"><span class="pre">STARTTLS</span></code>) and
use the <cite>john</cite> username. Password will be prompted securely.</p>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">To use a raw <code class="docutils literal"><span class="pre">TLS</span></code> connection, you can also use the
<code class="docutils literal"><span class="pre">--tls</span></code> flag.</p>
</div>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">You can also try to deliver email over <a class="reference external" href="https://www.torproject.org/">Tor</a> network with the <code class="docutils literal"><span class="pre">--tor</span></code>
option. Be be aware that a lot of email providers block Tor
exit nodes for spam control. You may need to use your
provider’s hidden service to workaround those issues. Ask
your email provider for Tor support if you have problems with
the SMTP method.</p>
</div>
</div>
</div>
<div class="section" id="configuration-files">
<span id="id1"></span><h2>Configuration files<a class="headerlink" href="#configuration-files" title="Permalink to this headline">¶</a></h2>
<p>Monkeysign will read <code class="docutils literal"><span class="pre">/etc/monkeysign.conf</span></code> and
<code class="docutils literal"><span class="pre">~/.config/monkeysign.conf</span></code> (in that order) for configuration
options. Each option can be specified on its own line. Lines starting
with the pound sign (<code class="docutils literal"><span class="pre">#</span></code>) are ignored as comments. A configuration
file can be generated with the <code class="docutils literal"><span class="pre">--save</span></code> option, or through the
preferences window in the GUI. Here is a sample configuration file:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># use my SMTP server to send email</span>
<span class="n">smtpserver</span><span class="o">=</span><span class="n">smtp</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="p">:</span><span class="mi">587</span>
<span class="c1"># this is my username, password is securely prompted interactively</span>
<span class="n">smtpuser</span><span class="o">=</span><span class="n">john</span>
<span class="c1"># be more verbose</span>
<span class="n">verbose</span>
</pre></div>
</div>
<p>As you can see, flags like <code class="docutils literal"><span class="pre">--verbose</span></code> are simply specified on their
own, while options with arguments need to be seperated with an equal
(<code class="docutils literal"><span class="pre">=</span></code>) sign.</p>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="support.html" class="btn btn-neutral float-right" title="Support" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="install.html" class="btn btn-neutral" title="Install" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
© Copyright 2014-2017, Antoine Beaupré and Emma Peel.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'2.2.3',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
|