diff options
Diffstat (limited to 'docs/_build/html/gnupg.html')
| -rw-r--r-- | docs/_build/html/gnupg.html | 2721 |
1 files changed, 2721 insertions, 0 deletions
diff --git a/docs/_build/html/gnupg.html b/docs/_build/html/gnupg.html new file mode 100644 index 0000000..63e8513 --- /dev/null +++ b/docs/_build/html/gnupg.html @@ -0,0 +1,2721 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>gnupg package — gnupg unknown documentation</title> + + <link rel="stylesheet" href="_static/agogo.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: './', + VERSION: 'unknown', + 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> + <link rel="top" title="gnupg unknown documentation" href="index.html" /> + <link rel="prev" title="gnupg: Python Package Documentation" href="index.html" /> + </head> + <body> + <div class="header-wrapper"> + <div class="header"> + <div class="headertitle"><a + href="index.html">gnupg: Python Module Documentation</a></div> + <div class="rel"> + <a href="index.html" title="gnupg: Python Package Documentation" + accesskey="P">previous</a> | + <a href="py-modindex.html" title="Python Module Index" + >modules</a> | + <a href="genindex.html" title="General Index" + accesskey="I">index</a> + </div> + </div> + </div> + + <div class="content-wrapper"> + <div class="content"> + <div class="document"> + + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="gnupg-package"> +<h1>gnupg package<a class="headerlink" href="#gnupg-package" title="Permalink to this headline">¶</a></h1> +<div class="section" id="gnupg-module"> +<h2>gnupg module<a class="headerlink" href="#gnupg-module" title="Permalink to this headline">¶</a></h2> +<p>This module contains public classes for working with <a class="reference external" href="http://gnupg.org">GnuPG</a>. To get started, +do:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">gnupg</span> +<span class="gp">>>> </span><span class="n">gpg</span> <span class="o">=</span> <span class="n">gnupg</span><span class="o">.</span><span class="n">GPG</span><span class="p">()</span> +</pre></div> +</div> +<span class="target" id="module-gnupg"></span><dl class="class"> +<dt id="gnupg.GPG"> +<em class="property">class </em><tt class="descname">GPG</tt><big>(</big><em>binary=None</em>, <em>homedir=None</em>, <em>verbose=False</em>, <em>use_agent=False</em>, <em>keyring=None</em>, <em>secring=None</em>, <em>options=None</em><big>)</big><a class="headerlink" href="#gnupg.GPG" title="Permalink to this definition">¶</a></dt> +<dd><p>Bases: <a class="reference internal" href="#gnupg._meta.GPGBase" title="gnupg._meta.GPGBase"><tt class="xref py py-class docutils literal"><span class="pre">gnupg._meta.GPGBase</span></tt></a></p> +<p>Python interface for handling interactions with GnuPG, including keyfile +generation, keyring maintainance, import and export, encryption and +decryption, sending to and recieving from keyservers, and signing and +verification.</p> +<p>Initialize a GnuPG process wrapper.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><strong>binary</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – Name for GnuPG binary executable. If the absolute +path is not given, the environment variable +<tt class="docutils literal"><span class="pre">$PATH</span></tt> is searched for the executable and +checked that the real uid/gid of the user has +sufficient permissions.</li> +<li><strong>homedir</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – Full pathname to directory containing the public +and private keyrings. Default is whatever GnuPG +defaults to.</li> +<li><strong>verbose</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><tt class="xref py py-obj docutils literal"><span class="pre">str</span></tt></a> or <a class="reference external" href="http://docs.python.org/library/functions.html#int" title="(in Python v2.7)"><tt class="xref py py-obj docutils literal"><span class="pre">int</span></tt></a> or <a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><tt class="xref py py-obj docutils literal"><span class="pre">bool</span></tt></a>) – String or numeric value to pass to GnuPG’s +<tt class="docutils literal"><span class="pre">--debug-level</span></tt> option. See the GnuPG man page for +the list of valid options. If False, debug output is +not generated by the GnuPG binary. If True, defaults +to <tt class="docutils literal"><span class="pre">--debug-level</span> <span class="pre">basic.</span></tt></li> +<li><strong>keyring</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – Name of keyring file containing public key data. +If unspecified, defaults to <tt class="file docutils literal"><span class="pre">pubring.gpg</span></tt> in +the <strong>homedir</strong> directory.</li> +<li><strong>secring</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – Name of alternative secret keyring file to use. If +left unspecified, this will default to using +<tt class="file docutils literal"><span class="pre">secring.gpg</span></tt> in the <strong>homedir</strong> directory, +and create that file if it does not exist.</li> +<li><strong>options</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#list" title="(in Python v2.7)"><em>list</em></a>) – A list of additional options to pass to the GnuPG +binary.</li> +</ul> +</td> +</tr> +<tr class="field-even field"><th class="field-name">Raises:</th><td class="field-body"><p class="first last">A <a class="reference external" href="http://docs.python.org/library/exceptions.html#exceptions.RuntimeError" title="(in Python v2.7)"><tt class="xref py py-exc docutils literal"><span class="pre">RuntimeError</span></tt></a> with explanation message +if there is a problem invoking GnuPG.</p> +</td> +</tr> +</tbody> +</table> +<p>Example:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">gnupg</span> +<span class="go">GnuPG logging disabled...</span> +<span class="gp">>>> </span><span class="n">gpg</span> <span class="o">=</span> <span class="n">gnupg</span><span class="o">.</span><span class="n">GPG</span><span class="p">(</span><span class="n">homedir</span><span class="o">=</span><span class="s">'doctests'</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">gpg</span><span class="o">.</span><span class="n">keyring</span> +<span class="go">'./doctests/pubring.gpg'</span> +<span class="gp">>>> </span><span class="n">gpg</span><span class="o">.</span><span class="n">secring</span> +<span class="go">'./doctests/secring.gpg'</span> +<span class="gp">>>> </span><span class="n">gpg</span><span class="o">.</span><span class="n">use_agent</span> +<span class="go">False</span> +<span class="gp">>>> </span><span class="n">gpg</span><span class="o">.</span><span class="n">binary</span> +<span class="go">'/usr/bin/gpg'</span> +</pre></div> +</div> +<dl class="attribute"> +<dt id="gnupg.GPG._batch_limit"> +<tt class="descname">_batch_limit</tt><em class="property"> = 25</em><a class="headerlink" href="#gnupg.GPG._batch_limit" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG._create_trustdb"> +<tt class="descname">_create_trustdb</tt><big>(</big><big>)</big><a class="headerlink" href="#gnupg.GPG._create_trustdb" title="Permalink to this definition">¶</a></dt> +<dd><p>Create the trustdb file in our homedir, if it doesn’t exist.</p> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG._export_ownertrust"> +<tt class="descname">_export_ownertrust</tt><big>(</big><em>trustdb=None</em><big>)</big><a class="headerlink" href="#gnupg.GPG._export_ownertrust" title="Permalink to this definition">¶</a></dt> +<dd><p>Export ownertrust to a trustdb file.</p> +<p>If there is already a file named <tt class="file docutils literal"><span class="pre">trustdb.gpg</span></tt> in the current GnuPG +homedir, it will be renamed to <tt class="file docutils literal"><span class="pre">trustdb.gpg.bak</span></tt>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>trustdb</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#module-string" title="(in Python v2.7)"><em>string</em></a>) – The path to the trustdb.gpg file. If not given, +defaults to <tt class="docutils literal"><span class="pre">'trustdb.gpg'</span></tt> in the current GnuPG +homedir.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG._fix_trustdb"> +<tt class="descname">_fix_trustdb</tt><big>(</big><em>trustdb=None</em><big>)</big><a class="headerlink" href="#gnupg.GPG._fix_trustdb" title="Permalink to this definition">¶</a></dt> +<dd><p>Attempt to repair a broken trustdb.gpg file.</p> +<p>GnuPG>=2.0.x has this magical-seeming flag: <cite>–fix-trustdb</cite>. You’d think +it would fix the the trustdb. Hah! It doesn’t. Here’s what it does +instead:</p> +<div class="highlight-python"><div class="highlight"><pre>(gpg)~/code/python-gnupg $ gpg2 --fix-trustdb +gpg: You may try to re-create the trustdb using the commands: +gpg: cd ~/.gnupg +gpg: gpg2 --export-ownertrust > otrust.tmp +gpg: rm trustdb.gpg +gpg: gpg2 --import-ownertrust < otrust.tmp +gpg: If that does not work, please consult the manual +</pre></div> +</div> +<p>Brilliant piece of software engineering right there.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>trustdb</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The path to the trustdb.gpg file. If not given, +defaults to <tt class="file docutils literal"><span class="pre">trustdb.gpg</span></tt> in the current GnuPG +homedir.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG._import_ownertrust"> +<tt class="descname">_import_ownertrust</tt><big>(</big><em>trustdb=None</em><big>)</big><a class="headerlink" href="#gnupg.GPG._import_ownertrust" title="Permalink to this definition">¶</a></dt> +<dd><p>Import ownertrust from a trustdb file.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>trustdb</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The path to the trustdb.gpg file. If not given, +defaults to <tt class="file docutils literal"><span class="pre">trustdb.gpg</span></tt> in the current GnuPG +homedir.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG.decrypt"> +<tt class="descname">decrypt</tt><big>(</big><em>message</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#gnupg.GPG.decrypt" title="Permalink to this definition">¶</a></dt> +<dd><p>Decrypt the contents of a string or file-like object <tt class="docutils literal"><span class="pre">message</span></tt>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>message</strong> (file or str or <a class="reference external" href="http://docs.python.org/library/io.html#io.BytesIO" title="(in Python v2.7)"><tt class="xref py py-class docutils literal"><span class="pre">io.BytesIO</span></tt></a>) – A string or file-like object to decrypt.</li> +<li><strong>always_trust</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – Instruct GnuPG to ignore trust checks.</li> +<li><strong>passphrase</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The passphrase for the secret key used for decryption.</li> +<li><strong>output</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – A filename to write the decrypted output to.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG.decrypt_file"> +<tt class="descname">decrypt_file</tt><big>(</big><em>filename</em>, <em>always_trust=False</em>, <em>passphrase=None</em>, <em>output=None</em><big>)</big><a class="headerlink" href="#gnupg.GPG.decrypt_file" title="Permalink to this definition">¶</a></dt> +<dd><p>Decrypt the contents of a file-like object <tt class="docutils literal"><span class="pre">filename</span></tt> .</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>filename</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – A file-like object to decrypt.</li> +<li><strong>always_trust</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – Instruct GnuPG to ignore trust checks.</li> +<li><strong>passphrase</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The passphrase for the secret key used for decryption.</li> +<li><strong>output</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – A filename to write the decrypted output to.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG.delete_keys"> +<tt class="descname">delete_keys</tt><big>(</big><em>fingerprints</em>, <em>secret=False</em>, <em>subkeys=False</em><big>)</big><a class="headerlink" href="#gnupg.GPG.delete_keys" title="Permalink to this definition">¶</a></dt> +<dd><p>Delete a key, or list of keys, from the current keyring.</p> +<p>The keys must be referred to by their full fingerprints for GnuPG to +delete them. If <tt class="docutils literal"><span class="pre">secret=True</span></tt>, the corresponding secret keyring will +be deleted from <a class="reference internal" href="#gnupg._parsers.GenKey.secring" title="gnupg._parsers.GenKey.secring"><tt class="xref py py-obj docutils literal"><span class="pre">secring</span></tt></a>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>fingerprints</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><tt class="xref py py-obj docutils literal"><span class="pre">str</span></tt></a> or <a class="reference external" href="http://docs.python.org/library/functions.html#list" title="(in Python v2.7)"><tt class="xref py py-obj docutils literal"><span class="pre">list</span></tt></a> or <a class="reference external" href="http://docs.python.org/library/functions.html#tuple" title="(in Python v2.7)"><tt class="xref py py-obj docutils literal"><span class="pre">tuple</span></tt></a>) – A string, or a list/tuple of strings, +representing the fingerprint(s) for the key(s) +to delete.</li> +<li><strong>secret</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, delete the corresponding secret key(s) +also. (default: False)</li> +<li><strong>subkeys</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, delete the secret subkey first, then the +public key. (default: False) Same as: +<strong class="command">$gpg –delete-secret-and-public-key 0x12345678</strong>.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG.encrypt"> +<tt class="descname">encrypt</tt><big>(</big><em>data</em>, <em>*recipients</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#gnupg.GPG.encrypt" title="Permalink to this definition">¶</a></dt> +<dd><p>Encrypt the message contained in <tt class="docutils literal"><span class="pre">data</span></tt> to <tt class="docutils literal"><span class="pre">recipients</span></tt>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>data</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The file or bytestream to encrypt.</li> +<li><strong>recipients</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The recipients to encrypt to. Recipients must +be specified keyID/fingerprint. Care should be taken in Python2.x +to make sure that the given fingerprint is in fact a string and +not a unicode object.</li> +<li><strong>default_key</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The keyID/fingerprint of the key to use for +signing. If given, <tt class="docutils literal"><span class="pre">data</span></tt> will be encrypted and signed.</li> +<li><strong>passphrase</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – If given, and <tt class="docutils literal"><span class="pre">default_key</span></tt> is also given, +use this passphrase to unlock the secret portion of the +<tt class="docutils literal"><span class="pre">default_key</span></tt> to sign the encrypted <tt class="docutils literal"><span class="pre">data</span></tt>. Otherwise, if +<tt class="docutils literal"><span class="pre">default_key</span></tt> is not given, but <tt class="docutils literal"><span class="pre">symmetric=True</span></tt>, then use +this passphrase as the passphrase for symmetric +encryption. Signing and symmetric encryption should <em>not</em> be +combined when sending the <tt class="docutils literal"><span class="pre">data</span></tt> to other recipients, else the +passphrase to the secret key would be shared with them.</li> +<li><strong>armor</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, ascii armor the output; otherwise, the +output will be in binary format. (Default: True)</li> +<li><strong>encrypt</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, encrypt the <tt class="docutils literal"><span class="pre">data</span></tt> using the +<tt class="docutils literal"><span class="pre">recipients</span></tt> public keys. (Default: True)</li> +<li><strong>symmetric</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, encrypt the <tt class="docutils literal"><span class="pre">data</span></tt> to <tt class="docutils literal"><span class="pre">recipients</span></tt> +using a symmetric key. See the <tt class="docutils literal"><span class="pre">passphrase</span></tt> parameter. Symmetric +encryption and public key encryption can be used simultaneously, +and will result in a ciphertext which is decryptable with either +the symmetric <tt class="docutils literal"><span class="pre">passphrase</span></tt> or one of the corresponding private +keys.</li> +<li><strong>always_trust</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, ignore trust warnings on recipient +keys. If False, display trust warnings. (default: True)</li> +<li><strong>output</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The output file to write to. If not specified, the +encrypted output is returned, and thus should be stored as an +object in Python. For example:</li> +</ul> +</td> +</tr> +</tbody> +</table> +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">shutil</span> +<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">gnupg</span> +<span class="gp">>>> </span><span class="k">if</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">exists</span><span class="p">(</span><span class="s">"doctests"</span><span class="p">):</span> +<span class="gp">... </span> <span class="n">shutil</span><span class="o">.</span><span class="n">rmtree</span><span class="p">(</span><span class="s">"doctests"</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">gpg</span> <span class="o">=</span> <span class="n">gnupg</span><span class="o">.</span><span class="n">GPG</span><span class="p">(</span><span class="n">homedir</span><span class="o">=</span><span class="s">"doctests"</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">key_settings</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">gen_key_input</span><span class="p">(</span><span class="n">key_type</span><span class="o">=</span><span class="s">'RSA'</span><span class="p">,</span> +<span class="gp">... </span> <span class="n">key_length</span><span class="o">=</span><span class="mi">1024</span><span class="p">,</span> +<span class="gp">... </span> <span class="n">key_usage</span><span class="o">=</span><span class="s">'ESCA'</span><span class="p">,</span> +<span class="gp">... </span> <span class="n">passphrase</span><span class="o">=</span><span class="s">'foo'</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">key</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">gen_key</span><span class="p">(</span><span class="n">key_settings</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">message</span> <span class="o">=</span> <span class="s">"The crow flies at midnight."</span> +<span class="gp">>>> </span><span class="n">encrypted</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">gpg</span><span class="o">.</span><span class="n">encrypt</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">key</span><span class="o">.</span><span class="n">printprint</span><span class="p">))</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">encrypted</span> <span class="o">!=</span> <span class="n">message</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="ow">not</span> <span class="n">encrypted</span><span class="o">.</span><span class="n">isspace</span><span class="p">()</span> +<span class="gp">>>> </span><span class="n">decrypted</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">gpg</span><span class="o">.</span><span class="n">decrypt</span><span class="p">(</span><span class="n">encrypted</span><span class="p">))</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="ow">not</span> <span class="n">decrypted</span><span class="o">.</span><span class="n">isspace</span><span class="p">()</span> +<span class="gp">>>> </span><span class="n">decrypted</span> +<span class="go">'The crow flies at midnight.'</span> +</pre></div> +</div> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>cipher_algo</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The cipher algorithm to use. To see available +algorithms with your version of GnuPG, do: +<strong class="command">$ gpg –with-colons –list-config ciphername</strong>. +The default <tt class="docutils literal"><span class="pre">cipher_algo</span></tt>, if unspecified, is <tt class="docutils literal"><span class="pre">'AES256'</span></tt>.</li> +<li><strong>digest_algo</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The hash digest to use. Again, to see which +hashes your GnuPG is capable of using, do: +<strong class="command">$ gpg –with-colons –list-config digestname</strong>. +The default, if unspecified, is <tt class="docutils literal"><span class="pre">'SHA512'</span></tt>.</li> +<li><strong>compress_algo</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The compression algorithm to use. Can be one +of <tt class="docutils literal"><span class="pre">'ZLIB'</span></tt>, <tt class="docutils literal"><span class="pre">'BZIP2'</span></tt>, <tt class="docutils literal"><span class="pre">'ZIP'</span></tt>, or <tt class="docutils literal"><span class="pre">'Uncompressed'</span></tt>.</li> +</ul> +</td> +</tr> +</tbody> +</table> +<div class="admonition seealso"> +<p class="first admonition-title">See also</p> +<p class="last"><a class="reference internal" href="#gnupg._meta.GPGBase._encrypt" title="gnupg._meta.GPGBase._encrypt"><tt class="xref py py-meth docutils literal"><span class="pre">_encrypt()</span></tt></a></p> +</div> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG.export_keys"> +<tt class="descname">export_keys</tt><big>(</big><em>keyids</em>, <em>secret=False</em>, <em>subkeys=False</em><big>)</big><a class="headerlink" href="#gnupg.GPG.export_keys" title="Permalink to this definition">¶</a></dt> +<dd><p>Export the indicated <tt class="docutils literal"><span class="pre">keyids</span></tt>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>keyids</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – A keyid or fingerprint in any format that GnuPG will +accept.</li> +<li><strong>secret</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, export only the secret key.</li> +<li><strong>subkeys</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, export the secret subkeys.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG.gen_key"> +<tt class="descname">gen_key</tt><big>(</big><em>input</em><big>)</big><a class="headerlink" href="#gnupg.GPG.gen_key" title="Permalink to this definition">¶</a></dt> +<dd><p>Generate a GnuPG key through batch file key generation. See +<a class="reference internal" href="#gnupg.GPG.gen_key_input" title="gnupg.GPG.gen_key_input"><tt class="xref py py-meth docutils literal"><span class="pre">GPG.gen_key_input()</span></tt></a> for creating the control input.</p> +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">gnupg</span> +<span class="gp">>>> </span><span class="n">gpg</span> <span class="o">=</span> <span class="n">gnupg</span><span class="o">.</span><span class="n">GPG</span><span class="p">(</span><span class="n">homedir</span><span class="o">=</span><span class="s">"doctests"</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">key_input</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">gen_key_input</span><span class="p">()</span> +<span class="gp">>>> </span><span class="n">key</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">gen_key</span><span class="p">(</span><span class="n">key_input</span><span class="p">)</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">key</span><span class="o">.</span><span class="n">fingerprint</span> +</pre></div> +</div> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>input</strong> (<a class="reference external" href="http://docs.python.org/library/stdtypes.html#dict" title="(in Python v2.7)"><em>dict</em></a>) – A dictionary of parameters and values for the new +key.</td> +</tr> +<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">The result mapping with details of the new key, which is a +<a class="reference internal" href="#gnupg._parsers.GenKey" title="gnupg._parsers.GenKey"><tt class="xref py py-class docutils literal"><span class="pre">GenKey</span></tt></a> object.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG.gen_key_input"> +<tt class="descname">gen_key_input</tt><big>(</big><em>separate_keyring=False</em>, <em>save_batchfile=False</em>, <em>testing=False</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#gnupg.GPG.gen_key_input" title="Permalink to this definition">¶</a></dt> +<dd><p>Generate a batch file for input to <a class="reference internal" href="#gnupg.GPG.gen_key" title="gnupg.GPG.gen_key"><tt class="xref py py-meth docutils literal"><span class="pre">gen_key()</span></tt></a>.</p> +<p>The GnuPG batch file key generation feature allows unattended key +generation by creating a file with special syntax and then providing it +to: <strong class="command">gpg –gen-key –batch</strong>. Batch files look like this:</p> +<div class="line-block"> +<div class="line">Name-Real: Alice</div> +<div class="line">Name-Email: <a class="reference external" href="mailto:alice%40inter.net">alice<span>@</span>inter<span>.</span>net</a></div> +<div class="line">Expire-Date: 2014-04-01</div> +<div class="line">Key-Type: RSA</div> +<div class="line">Key-Length: 4096</div> +<div class="line">Key-Usage: cert</div> +<div class="line">Subkey-Type: RSA</div> +<div class="line">Subkey-Length: 4096</div> +<div class="line">Subkey-Usage: encrypt,sign,auth</div> +<div class="line">Passphrase: sekrit</div> +<div class="line">%pubring foo.gpg</div> +<div class="line">%secring sec.gpg</div> +<div class="line">%commit</div> +</div> +<p>which is what this function creates for you. All of the available, +non-control parameters are detailed below (control parameters are the +ones which begin with a ‘%’). For example, to generate the batch file +example above, use like this:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">gnupg</span> +<span class="go">GnuPG logging disabled...</span> +<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">__future__</span> <span class="kn">import</span> <span class="n">print_function</span> +<span class="gp">>>> </span><span class="n">gpg</span> <span class="o">=</span> <span class="n">gnupg</span><span class="o">.</span><span class="n">GPG</span><span class="p">(</span><span class="n">homedir</span><span class="o">=</span><span class="s">'doctests'</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">alice</span> <span class="o">=</span> <span class="p">{</span> <span class="s">'name_real'</span><span class="p">:</span> <span class="s">'Alice'</span><span class="p">,</span> +<span class="gp">... </span> <span class="s">'name_email'</span><span class="p">:</span> <span class="s">'alice@inter.net'</span><span class="p">,</span> +<span class="gp">... </span> <span class="s">'expire_date'</span><span class="p">:</span> <span class="s">'2014-04-01'</span><span class="p">,</span> +<span class="gp">... </span> <span class="s">'key_type'</span><span class="p">:</span> <span class="s">'RSA'</span><span class="p">,</span> +<span class="gp">... </span> <span class="s">'key_length'</span><span class="p">:</span> <span class="mi">4096</span><span class="p">,</span> +<span class="gp">... </span> <span class="s">'key_usage'</span><span class="p">:</span> <span class="s">''</span><span class="p">,</span> +<span class="gp">... </span> <span class="s">'subkey_type'</span><span class="p">:</span> <span class="s">'RSA'</span><span class="p">,</span> +<span class="gp">... </span> <span class="s">'subkey_length'</span><span class="p">:</span> <span class="mi">4096</span><span class="p">,</span> +<span class="gp">... </span> <span class="s">'subkey_usage'</span><span class="p">:</span> <span class="s">'encrypt,sign,auth'</span><span class="p">,</span> +<span class="gp">... </span> <span class="s">'passphrase'</span><span class="p">:</span> <span class="s">'sekrit'</span><span class="p">}</span> +<span class="gp">>>> </span><span class="n">alice_input</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">gen_key_input</span><span class="p">(</span><span class="o">**</span><span class="n">alice</span><span class="p">)</span> +<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">alice_input</span><span class="p">)</span> +<span class="go">Key-Type: RSA</span> +<span class="go">Subkey-Type: RSA</span> +<span class="go">Subkey-Usage: encrypt,sign,auth</span> +<span class="go">Expire-Date: 2014-04-01</span> +<span class="go">Passphrase: sekrit</span> +<span class="go">Name-Real: Alice</span> +<span class="go">Name-Email: alice@inter.net</span> +<span class="go">Key-Length: 4096</span> +<span class="go">Subkey-Length: 4096</span> +<span class="go">%pubring ./doctests/alice.pubring.gpg</span> +<span class="go">%secring ./doctests/alice.secring.gpg</span> +<span class="go">%commit</span> + +<span class="gp">>>> </span><span class="n">alice_key</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">gen_key</span><span class="p">(</span><span class="n">alice_input</span><span class="p">)</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">alice_key</span> <span class="ow">is</span> <span class="ow">not</span> <span class="bp">None</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">alice_key</span><span class="o">.</span><span class="n">fingerprint</span> <span class="ow">is</span> <span class="ow">not</span> <span class="bp">None</span> +<span class="gp">>>> </span><span class="n">message</span> <span class="o">=</span> <span class="s">"no one else can read my sekrit message"</span> +<span class="gp">>>> </span><span class="n">encrypted</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">encrypt</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">alice_key</span><span class="o">.</span><span class="n">fingerprint</span><span class="p">)</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">encrypted</span><span class="o">.</span><span class="n">data</span><span class="p">,</span> <span class="nb">str</span><span class="p">)</span> +</pre></div> +</div> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><strong>separate_keyring</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – Specify for the new key to be written to +a separate pubring.gpg and secring.gpg. If True, +<a class="reference internal" href="#gnupg.GPG.gen_key" title="gnupg.GPG.gen_key"><tt class="xref py py-meth docutils literal"><span class="pre">gen_key()</span></tt></a> will automatically rename the separate +keyring and secring to whatever the fingerprint of the generated +key ends up being, suffixed with ‘.pubring’ and ‘.secring’ +respectively.</li> +<li><strong>save_batchfile</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – Save a copy of the generated batch file to +disk in a file named <name_real>.batch, where <name_real> is the +<tt class="docutils literal"><span class="pre">name_real</span></tt> parameter stripped of punctuation, spaces, and +non-ascii characters.</li> +<li><strong>testing</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – Uses a faster, albeit insecure random number +generator to create keys. This should only be used for testing +purposes, for keys which are going to be created and then soon +after destroyed, and never for the generation of actual use keys.</li> +<li><strong>name_real</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The name field of the UID in the generated key.</li> +<li><strong>name_comment</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The comment in the UID of the generated key.</li> +<li><strong>name_email</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The email in the UID of the generated key. +(default: <tt class="docutils literal"><span class="pre">$USER</span></tt> @ <strong class="command">hostname</strong> ) Remember to use UTF-8 +encoding for the entirety of the UID. At least one of +<tt class="docutils literal"><span class="pre">name_real</span></tt>, <tt class="docutils literal"><span class="pre">name_comment</span></tt>, or <tt class="docutils literal"><span class="pre">name_email</span></tt> must be +provided, or else no user ID is created.</li> +<li><strong>key_type</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – One of ‘RSA’, ‘DSA’, ‘ELG-E’, or ‘default’. +(default: ‘RSA’, if using GnuPG v1.x, otherwise ‘default’) Starts +a new parameter block by giving the type of the primary key. The +algorithm must be capable of signing. This is a required +parameter. The algorithm may either be an OpenPGP algorithm number +or a string with the algorithm name. The special value ‘default’ +may be used for algo to create the default key type; in this case +a <tt class="docutils literal"><span class="pre">key_usage</span></tt> should not be given and ‘default’ must also be +used for <tt class="docutils literal"><span class="pre">subkey_type</span></tt>.</li> +<li><strong>key_length</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#int" title="(in Python v2.7)"><em>int</em></a>) – The requested length of the generated key in +bits. (Default: 4096)</li> +<li><strong>key_grip</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – hexstring This is an optional hexidecimal string +which is used to generate a CSR or certificate for an already +existing key. <tt class="docutils literal"><span class="pre">key_length</span></tt> will be ignored if this parameter +is given.</li> +<li><strong>key_usage</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – Space or comma delimited string of key +usages. Allowed values are ‘encrypt’, ‘sign’, and ‘auth’. This is +used to generate the key flags. Please make sure that the +algorithm is capable of this usage. Note that OpenPGP requires +that all primary keys are capable of certification, so no matter +what usage is given here, the ‘cert’ flag will be on. If no +‘Key-Usage’ is specified and the ‘Key-Type’ is not ‘default’, all +allowed usages for that particular algorithm are used; if it is +not given but ‘default’ is used the usage will be ‘sign’.</li> +<li><strong>subkey_type</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – This generates a secondary key +(subkey). Currently only one subkey can be handled. See also +<tt class="docutils literal"><span class="pre">key_type</span></tt> above.</li> +<li><strong>subkey_length</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#int" title="(in Python v2.7)"><em>int</em></a>) – The length of the secondary subkey in bits.</li> +<li><strong>subkey_usage</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – Key usage for a subkey; similar to +<tt class="docutils literal"><span class="pre">key_usage</span></tt>.</li> +<li><strong>expire_date</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#int" title="(in Python v2.7)"><tt class="xref py py-obj docutils literal"><span class="pre">int</span></tt></a> or <a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><tt class="xref py py-obj docutils literal"><span class="pre">str</span></tt></a>) – Can be specified as an iso-date or as +<int>[d|w|m|y] Set the expiration date for the key (and the +subkey). It may either be entered in ISO date format (2000-08-15) +or as number of days, weeks, month or years. The special notation +“seconds=N” is also allowed to directly give an Epoch +value. Without a letter days are assumed. Note that there is no +check done on the overflow of the type used by OpenPGP for +timestamps. Thus you better make sure that the given value make +sense. Although OpenPGP works with time intervals, GnuPG uses an +absolute value internally and thus the last year we can represent +is 2105.</li> +<li><strong>creation_date</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – Set the creation date of the key as stored +in the key information and which is also part of the fingerprint +calculation. Either a date like “1986-04-26” or a full timestamp +like “19860426T042640” may be used. The time is considered to be +UTC. If it is not given the current time is used.</li> +<li><strong>passphrase</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The passphrase for the new key. The default is +to not use any passphrase. Note that GnuPG>=2.1.x will not allow +you to specify a passphrase for batch key generation – GnuPG will +ignore the <strong>passphrase</strong> parameter, stop, and ask the user for +the new passphrase. However, we can put the command +<tt class="docutils literal"><span class="pre">%no-protection</span></tt> into the batch key generation file to allow a +passwordless key to be created, which can then have its passphrase +set later with <tt class="docutils literal"><span class="pre">--edit-key</span></tt>.</li> +<li><strong>preferences</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – Set the cipher, hash, and compression +preference values for this key. This expects the same type of +string as the sub-command ‘setpref’ in the –edit-key menu.</li> +<li><strong>revoker</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – Should be given as ‘algo:fpr’ (case sensitive). +Add a designated revoker to the generated key. Algo is the public +key algorithm of the designated revoker (i.e. RSA=1, DSA=17, etc.) +fpr is the fingerprint of the designated revoker. The optional +‘sensitive’ flag marks the designated revoker as sensitive +information. Only v4 keys may be designated revokers.</li> +<li><strong>keyserver</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – This is an optional parameter that specifies the +preferred keyserver URL for the key.</li> +<li><strong>handle</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – This is an optional parameter only used with the +status lines <tt class="docutils literal"><span class="pre">KEY_CREATED</span></tt> and <tt class="docutils literal"><span class="pre">KEY_NOT_CREATED</span></tt>. string may +be up to 100 characters and should not contain spaces. It is +useful for batch key generation to associate a key parameter block +with a status line.</li> +</ul> +</td> +</tr> +<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body"><p class="first">str</p> +</td> +</tr> +<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">A suitable input string for the <a class="reference internal" href="#gnupg.GPG.gen_key" title="gnupg.GPG.gen_key"><tt class="xref py py-meth docutils literal"><span class="pre">GPG.gen_key()</span></tt></a> method, +the latter of which will create the new keypair.</p> +</td> +</tr> +</tbody> +</table> +<p>See <a class="reference external" href="http://www.gnupg.org/documentation/manuals/gnupg-devel/Unattended-GPG-key-generation.html">this GnuPG Manual section</a> for more details.</p> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG.import_keys"> +<tt class="descname">import_keys</tt><big>(</big><em>key_data</em><big>)</big><a class="headerlink" href="#gnupg.GPG.import_keys" title="Permalink to this definition">¶</a></dt> +<dd><p>Import the key_data into our keyring.</p> +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">shutil</span> +<span class="gp">>>> </span><span class="n">shutil</span><span class="o">.</span><span class="n">rmtree</span><span class="p">(</span><span class="s">"doctests"</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">gpg</span> <span class="o">=</span> <span class="n">gnupg</span><span class="o">.</span><span class="n">GPG</span><span class="p">(</span><span class="n">homedir</span><span class="o">=</span><span class="s">"doctests"</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">inpt</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">gen_key_input</span><span class="p">()</span> +<span class="gp">>>> </span><span class="n">key1</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">gen_key</span><span class="p">(</span><span class="n">inpt</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">print1</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">key1</span><span class="o">.</span><span class="n">fingerprint</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">pubkey1</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">export_keys</span><span class="p">(</span><span class="n">print1</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">seckey1</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">export_keys</span><span class="p">(</span><span class="n">print1</span><span class="p">,</span><span class="n">secret</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">key2</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">gen_key</span><span class="p">(</span><span class="n">inpt</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">print2</span> <span class="o">=</span> <span class="n">key2</span><span class="o">.</span><span class="n">fingerprint</span> +<span class="gp">>>> </span><span class="n">seckeys</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">list_keys</span><span class="p">(</span><span class="n">secret</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">pubkeys</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">list_keys</span><span class="p">()</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">print1</span> <span class="ow">in</span> <span class="n">seckeys</span><span class="o">.</span><span class="n">fingerprints</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">print1</span> <span class="ow">in</span> <span class="n">pubkeys</span><span class="o">.</span><span class="n">fingerprints</span> +<span class="gp">>>> </span><span class="nb">str</span><span class="p">(</span><span class="n">gpg</span><span class="o">.</span><span class="n">delete_keys</span><span class="p">(</span><span class="n">print1</span><span class="p">))</span> +<span class="go">'Must delete secret key first'</span> +<span class="gp">>>> </span><span class="nb">str</span><span class="p">(</span><span class="n">gpg</span><span class="o">.</span><span class="n">delete_keys</span><span class="p">(</span><span class="n">print1</span><span class="p">,</span><span class="n">secret</span><span class="o">=</span><span class="bp">True</span><span class="p">))</span> +<span class="go">'ok'</span> +<span class="gp">>>> </span><span class="nb">str</span><span class="p">(</span><span class="n">gpg</span><span class="o">.</span><span class="n">delete_keys</span><span class="p">(</span><span class="n">print1</span><span class="p">))</span> +<span class="go">'ok'</span> +<span class="gp">>>> </span><span class="n">pubkeys</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">list_keys</span><span class="p">()</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="ow">not</span> <span class="n">print1</span> <span class="ow">in</span> <span class="n">pubkeys</span><span class="o">.</span><span class="n">fingerprints</span> +<span class="gp">>>> </span><span class="n">result</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">import_keys</span><span class="p">(</span><span class="n">pubkey1</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">pubkeys</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">list_keys</span><span class="p">()</span> +<span class="gp">>>> </span><span class="n">seckeys</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">list_keys</span><span class="p">(</span><span class="n">secret</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="ow">not</span> <span class="n">print1</span> <span class="ow">in</span> <span class="n">seckeys</span><span class="o">.</span><span class="n">fingerprints</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">print1</span> <span class="ow">in</span> <span class="n">pubkeys</span><span class="o">.</span><span class="n">fingerprints</span> +<span class="gp">>>> </span><span class="n">result</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">import_keys</span><span class="p">(</span><span class="n">seckey1</span><span class="p">)</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">result</span> +<span class="gp">>>> </span><span class="n">seckeys</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">list_keys</span><span class="p">(</span><span class="n">secret</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">print1</span> <span class="ow">in</span> <span class="n">seckeys</span><span class="o">.</span><span class="n">fingerprints</span> +</pre></div> +</div> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG.is_gpg1"> +<tt class="descname">is_gpg1</tt><big>(</big><big>)</big><a class="headerlink" href="#gnupg.GPG.is_gpg1" title="Permalink to this definition">¶</a></dt> +<dd><p>Returns true if using GnuPG <= 1.x.</p> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG.is_gpg2"> +<tt class="descname">is_gpg2</tt><big>(</big><big>)</big><a class="headerlink" href="#gnupg.GPG.is_gpg2" title="Permalink to this definition">¶</a></dt> +<dd><p>Returns true if using GnuPG >= 2.x.</p> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG.list_keys"> +<tt class="descname">list_keys</tt><big>(</big><em>secret=False</em><big>)</big><a class="headerlink" href="#gnupg.GPG.list_keys" title="Permalink to this definition">¶</a></dt> +<dd><p>List the keys currently in the keyring.</p> +<p>The GnuPG option ‘–show-photos’, according to the GnuPG manual, “does +not work with –with-colons”, but since we can’t rely on all versions +of GnuPG to explicitly handle this correctly, we should probably +include it in the args.</p> +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">shutil</span> +<span class="gp">>>> </span><span class="n">shutil</span><span class="o">.</span><span class="n">rmtree</span><span class="p">(</span><span class="s">"doctests"</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">gpg</span> <span class="o">=</span> <span class="n">GPG</span><span class="p">(</span><span class="n">homedir</span><span class="o">=</span><span class="s">"doctests"</span><span class="p">)</span> +<span class="gp">>>> </span><span class="nb">input</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">gen_key_input</span><span class="p">()</span> +<span class="gp">>>> </span><span class="n">result</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">gen_key</span><span class="p">(</span><span class="nb">input</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">print1</span> <span class="o">=</span> <span class="n">result</span><span class="o">.</span><span class="n">fingerprint</span> +<span class="gp">>>> </span><span class="n">result</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">gen_key</span><span class="p">(</span><span class="nb">input</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">print2</span> <span class="o">=</span> <span class="n">result</span><span class="o">.</span><span class="n">fingerprint</span> +<span class="gp">>>> </span><span class="n">pubkeys</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">list_keys</span><span class="p">()</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">print1</span> <span class="ow">in</span> <span class="n">pubkeys</span><span class="o">.</span><span class="n">fingerprints</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">print2</span> <span class="ow">in</span> <span class="n">pubkeys</span><span class="o">.</span><span class="n">fingerprints</span> +</pre></div> +</div> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG.list_packets"> +<tt class="descname">list_packets</tt><big>(</big><em>raw_data</em><big>)</big><a class="headerlink" href="#gnupg.GPG.list_packets" title="Permalink to this definition">¶</a></dt> +<dd><p>List the packet contents of a file.</p> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG.list_sigs"> +<tt class="descname">list_sigs</tt><big>(</big><em>*keyids</em><big>)</big><a class="headerlink" href="#gnupg.GPG.list_sigs" title="Permalink to this definition">¶</a></dt> +<dd><p>Get the signatures for each of the <tt class="docutils literal"><span class="pre">keyids</span></tt>.</p> +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">gnupg</span> +<span class="gp">>>> </span><span class="n">gpg</span> <span class="o">=</span> <span class="n">gnupg</span><span class="o">.</span><span class="n">GPG</span><span class="p">(</span><span class="n">homedir</span><span class="o">=</span><span class="s">"doctests"</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">key_input</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">gen_key_input</span><span class="p">()</span> +<span class="gp">>>> </span><span class="n">key</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">gen_key</span><span class="p">(</span><span class="n">key_input</span><span class="p">)</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">key</span><span class="o">.</span><span class="n">fingerprint</span> +</pre></div> +</div> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body">dict</td> +</tr> +<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">A dictionary whose keys are the original keyid parameters, +and whose values are lists of signatures.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG.recv_keys"> +<tt class="descname">recv_keys</tt><big>(</big><em>*keyids</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#gnupg.GPG.recv_keys" title="Permalink to this definition">¶</a></dt> +<dd><p>Import keys from a keyserver.</p> +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">gpg</span> <span class="o">=</span> <span class="n">gnupg</span><span class="o">.</span><span class="n">GPG</span><span class="p">(</span><span class="n">homedir</span><span class="o">=</span><span class="s">"doctests"</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">key</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">recv_keys</span><span class="p">(</span><span class="s">'hkp://pgp.mit.edu'</span><span class="p">,</span> <span class="s">'3FF0DB166A7476EA'</span><span class="p">)</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">key</span> +</pre></div> +</div> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>keyids</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – Each <tt class="docutils literal"><span class="pre">keyids</span></tt> argument should be a string +containing a keyid to request.</li> +<li><strong>keyserver</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The keyserver to request the <tt class="docutils literal"><span class="pre">keyids</span></tt> from; +defaults to <cite>gnupg.GPG.keyserver</cite>.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG.sign"> +<tt class="descname">sign</tt><big>(</big><em>data</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#gnupg.GPG.sign" title="Permalink to this definition">¶</a></dt> +<dd><p>Create a signature for a message string or file.</p> +<p>Note that this method is not for signing other keys. (In GnuPG’s +terms, what we all usually call ‘keysigning’ is actually termed +‘certification’...) Even though they are cryptographically the same +operation, GnuPG differentiates between them, presumedly because these +operations are also the same as the decryption operation. If the +<tt class="docutils literal"><span class="pre">key_usage``s</span> <span class="pre">``C</span> <span class="pre">(certification)</span></tt>, <tt class="docutils literal"><span class="pre">S</span> <span class="pre">(sign)</span></tt>, and <tt class="docutils literal"><span class="pre">E</span> +<span class="pre">(encrypt)</span></tt>, were all the same key, the key would “wear down” through +frequent signing usage – since signing data is usually done often – +meaning that the secret portion of the keypair, also used for +decryption in this scenario, would have a statistically higher +probability of an adversary obtaining an oracle for it (or for a +portion of the rounds in the cipher algorithm, depending on the family +of cryptanalytic attack used).</p> +<p>In simpler terms: this function isn’t for signing your friends’ keys, +it’s for something like signing an email.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>data</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><tt class="xref py py-obj docutils literal"><span class="pre">str</span></tt></a> or <a class="reference external" href="http://docs.python.org/library/functions.html#file" title="(in Python v2.7)"><tt class="xref py py-obj docutils literal"><span class="pre">file</span></tt></a>) – A string or file stream to sign.</li> +<li><strong>default_key</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The key to sign with.</li> +<li><strong>passphrase</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The passphrase to pipe to stdin.</li> +<li><strong>clearsign</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, create a cleartext signature.</li> +<li><strong>detach</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, create a detached signature.</li> +<li><strong>binary</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, do not ascii armour the output.</li> +<li><strong>digest_algo</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The hash digest to use. Again, to see which +hashes your GnuPG is capable of using, do: +<strong class="command">$ gpg –with-colons –list-config digestname</strong>. +The default, if unspecified, is <tt class="docutils literal"><span class="pre">'SHA512'</span></tt>.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG.verify"> +<tt class="descname">verify</tt><big>(</big><em>data</em><big>)</big><a class="headerlink" href="#gnupg.GPG.verify" title="Permalink to this definition">¶</a></dt> +<dd><p>Verify the signature on the contents of the string <tt class="docutils literal"><span class="pre">data</span></tt>.</p> +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">gpg</span> <span class="o">=</span> <span class="n">GPG</span><span class="p">(</span><span class="n">homedir</span><span class="o">=</span><span class="s">"doctests"</span><span class="p">)</span> +<span class="gp">>>> </span><span class="nb">input</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">gen_key_input</span><span class="p">(</span><span class="n">Passphrase</span><span class="o">=</span><span class="s">'foo'</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">key</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">gen_key</span><span class="p">(</span><span class="nb">input</span><span class="p">)</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">key</span> +<span class="gp">>>> </span><span class="n">sig</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">sign</span><span class="p">(</span><span class="s">'hello'</span><span class="p">,</span><span class="n">keyid</span><span class="o">=</span><span class="n">key</span><span class="o">.</span><span class="n">fingerprint</span><span class="p">,</span><span class="n">passphrase</span><span class="o">=</span><span class="s">'bar'</span><span class="p">)</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="ow">not</span> <span class="n">sig</span> +<span class="gp">>>> </span><span class="n">sig</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">sign</span><span class="p">(</span><span class="s">'hello'</span><span class="p">,</span><span class="n">keyid</span><span class="o">=</span><span class="n">key</span><span class="o">.</span><span class="n">fingerprint</span><span class="p">,</span><span class="n">passphrase</span><span class="o">=</span><span class="s">'foo'</span><span class="p">)</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">sig</span> +<span class="gp">>>> </span><span class="n">verify</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">verify</span><span class="p">(</span><span class="n">sig</span><span class="o">.</span><span class="n">data</span><span class="p">)</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">verify</span> +</pre></div> +</div> +</dd></dl> + +<dl class="method"> +<dt id="gnupg.GPG.verify_file"> +<tt class="descname">verify_file</tt><big>(</big><em>file</em>, <em>sig_file=None</em><big>)</big><a class="headerlink" href="#gnupg.GPG.verify_file" title="Permalink to this definition">¶</a></dt> +<dd><p>Verify the signature on the contents of a file or file-like +object. Can handle embedded signatures as well as detached +signatures. If using detached signatures, the file containing the +detached signature should be specified as the <tt class="docutils literal"><span class="pre">sig_file</span></tt>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>file</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#file" title="(in Python v2.7)"><em>file</em></a>) – A file descriptor object. Its type will be checked +with <a class="reference internal" href="#gnupg._util._is_file" title="gnupg._util._is_file"><tt class="xref py py-func docutils literal"><span class="pre">_util._is_file()</span></tt></a>.</li> +<li><strong>sig_file</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – A file containing the GPG signature data for +<tt class="docutils literal"><span class="pre">file</span></tt>. If given, <tt class="docutils literal"><span class="pre">file</span></tt> is verified via this detached +signature.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +</dd></dl> + +</div> +<div class="section" id="meta-module"> +<span id="meta"></span><h2>meta module<a class="headerlink" href="#meta-module" title="Permalink to this headline">¶</a></h2> +<p>Contains the meta and base classes which <a class="reference internal" href="#gnupg.GPG" title="gnupg.GPG"><tt class="xref py py-class docutils literal"><span class="pre">gnupg.GPG</span></tt></a> inherits +from. Mostly, you shouldn’t ever need to touch anything in here, unless you’re +doing some serious hacking.</p> +<span class="target" id="module-gnupg._meta"></span><p>Meta and base classes for hiding internal functions, and controlling +attribute creation and handling.</p> +<dl class="class"> +<dt id="gnupg._meta.GPGMeta"> +<em class="property">class </em><tt class="descname">GPGMeta</tt><a class="reference internal" href="_modules/gnupg/_meta.html#GPGMeta"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGMeta" title="Permalink to this definition">¶</a></dt> +<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">type</span></tt></p> +<p>Metaclass for changing the :meth:GPG.__init__ initialiser.</p> +<p>Detects running gpg-agent processes and the presence of a pinentry +program, and disables pinentry so that python-gnupg can write the +passphrase to the controlled GnuPG process without killing the agent.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name" colspan="2">Attr _agent_proc:</th></tr> +<tr class="field-odd field"><td> </td><td class="field-body">If a <strong class="program">gpg-agent</strong> process is currently running +for the effective userid, then <strong>_agent_proc</strong> will be +set to a <tt class="docutils literal"><span class="pre">psutil.Process</span></tt> for that process.</td> +</tr> +</tbody> +</table> +<dl class="staticmethod"> +<dt id="gnupg._meta.GPGMeta.__new__"> +<em class="property">static </em><tt class="descname">__new__</tt><big>(</big><em>name</em>, <em>bases</em>, <em>attrs</em><big>)</big><a class="reference internal" href="_modules/gnupg/_meta.html#GPGMeta.__new__"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGMeta.__new__" title="Permalink to this definition">¶</a></dt> +<dd><p>Construct the initialiser for GPG</p> +</dd></dl> + +<dl class="classmethod"> +<dt id="gnupg._meta.GPGMeta._find_agent"> +<em class="property">classmethod </em><tt class="descname">_find_agent</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/gnupg/_meta.html#GPGMeta._find_agent"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGMeta._find_agent" title="Permalink to this definition">¶</a></dt> +<dd><p>Discover if a gpg-agent process for the current euid is running.</p> +<p>If there is a matching gpg-agent process, set a <tt class="xref py py-class docutils literal"><span class="pre">psutil.Process</span></tt> +instance containing the gpg-agent process’ information to +<tt class="docutils literal"><span class="pre">cls._agent_proc</span></tt>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">True if there exists a gpg-agent process running under the +same effective user ID as that of this program. Otherwise, +returns None.</td> +</tr> +</tbody> +</table> +</dd></dl> + +</dd></dl> + +<dl class="class"> +<dt id="gnupg._meta.GPGBase"> +<em class="property">class </em><tt class="descname">GPGBase</tt><big>(</big><em>binary=None</em>, <em>home=None</em>, <em>keyring=None</em>, <em>secring=None</em>, <em>use_agent=False</em>, <em>default_preference_list=None</em>, <em>verbose=False</em>, <em>options=None</em><big>)</big><a class="reference internal" href="_modules/gnupg/_meta.html#GPGBase"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGBase" title="Permalink to this definition">¶</a></dt> +<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></p> +<p>Base class for storing properties and controlling process initialisation.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name" colspan="2">Const _result_map:</th></tr> +<tr class="field-odd field"><td> </td><td class="field-body">A <em>dict</em> containing classes from +<a class="reference internal" href="#module-gnupg._parsers" title="gnupg._parsers"><tt class="xref py py-mod docutils literal"><span class="pre">_parsers</span></tt></a>, used for parsing results +obtained from GnuPG commands.</td> +</tr> +<tr class="field-even field"><th class="field-name" colspan="2">Const _decode_errors:</th></tr> +<tr class="field-even field"><td> </td><td class="field-body">How to handle encoding errors.</td> +</tr> +</tbody> +</table> +<p>Create a <tt class="docutils literal"><span class="pre">GPGBase</span></tt>.</p> +<p>This class is used to set up properties for controlling the behaviour +of configuring various options for GnuPG, such as setting GnuPG’s +<strong>homedir</strong> , and the paths to its <strong>binary</strong> and <strong>keyring</strong> .</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Const binary:</th><td class="field-body"><p class="first">(<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><tt class="xref py py-obj docutils literal"><span class="pre">str</span></tt></a>) The full path to the GnuPG binary.</p> +</td> +</tr> +<tr class="field-even field"><th class="field-name">Variables:</th><td class="field-body"><ul class="first last simple"> +<li><strong>homedir</strong> – (<a class="reference internal" href="#gnupg._util.InheritableProperty" title="gnupg._util.InheritableProperty"><tt class="xref py py-class docutils literal"><span class="pre">InheritableProperty</span></tt></a>) The full +path to the current setting for the GnuPG +<tt class="docutils literal"><span class="pre">--homedir</span></tt>.</li> +<li><strong>_generated_keys</strong> – (<a class="reference internal" href="#gnupg._util.InheritableProperty" title="gnupg._util.InheritableProperty"><tt class="xref py py-class docutils literal"><span class="pre">InheritableProperty</span></tt></a>) +Controls setting the directory for storing any +keys which are generated with +<a class="reference internal" href="#gnupg.GPG.gen_key" title="gnupg.GPG.gen_key"><tt class="xref py py-meth docutils literal"><span class="pre">gen_key()</span></tt></a>.</li> +<li><strong>keyring</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The filename in <strong>homedir</strong> to use as the keyring +file for public keys.</li> +<li><strong>secring</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The filename in <strong>homedir</strong> to use as the keyring +file for secret keys.</li> +</ul> +</td> +</tr> +</tbody> +</table> +<dl class="method"> +<dt id="gnupg._meta.GPGBase.__init__"> +<tt class="descname">__init__</tt><big>(</big><em>binary=None</em>, <em>home=None</em>, <em>keyring=None</em>, <em>secring=None</em>, <em>use_agent=False</em>, <em>default_preference_list=None</em>, <em>verbose=False</em>, <em>options=None</em><big>)</big><a class="reference internal" href="_modules/gnupg/_meta.html#GPGBase.__init__"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGBase.__init__" title="Permalink to this definition">¶</a></dt> +<dd><p>Create a <tt class="docutils literal"><span class="pre">GPGBase</span></tt>.</p> +<p>This class is used to set up properties for controlling the behaviour +of configuring various options for GnuPG, such as setting GnuPG’s +<strong>homedir</strong> , and the paths to its <strong>binary</strong> and <strong>keyring</strong> .</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Const binary:</th><td class="field-body"><p class="first">(<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><tt class="xref py py-obj docutils literal"><span class="pre">str</span></tt></a>) The full path to the GnuPG binary.</p> +</td> +</tr> +<tr class="field-even field"><th class="field-name">Variables:</th><td class="field-body"><ul class="first last simple"> +<li><strong>homedir</strong> – (<a class="reference internal" href="#gnupg._util.InheritableProperty" title="gnupg._util.InheritableProperty"><tt class="xref py py-class docutils literal"><span class="pre">InheritableProperty</span></tt></a>) The full +path to the current setting for the GnuPG +<tt class="docutils literal"><span class="pre">--homedir</span></tt>.</li> +<li><strong>_generated_keys</strong> – (<a class="reference internal" href="#gnupg._util.InheritableProperty" title="gnupg._util.InheritableProperty"><tt class="xref py py-class docutils literal"><span class="pre">InheritableProperty</span></tt></a>) +Controls setting the directory for storing any +keys which are generated with +<a class="reference internal" href="#gnupg.GPG.gen_key" title="gnupg.GPG.gen_key"><tt class="xref py py-meth docutils literal"><span class="pre">gen_key()</span></tt></a>.</li> +<li><strong>keyring</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The filename in <strong>homedir</strong> to use as the keyring +file for public keys.</li> +<li><strong>secring</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The filename in <strong>homedir</strong> to use as the keyring +file for secret keys.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg._meta.GPGBase.__remove_path__"> +<tt class="descname">__remove_path__</tt><big>(</big><em>prog=None</em>, <em>at_exit=True</em><big>)</big><a class="reference internal" href="_modules/gnupg/_meta.html#GPGBase.__remove_path__"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGBase.__remove_path__" title="Permalink to this definition">¶</a></dt> +<dd><p>Remove the directories containing a program from the system’s +<tt class="docutils literal"><span class="pre">$PATH</span></tt>. If <tt class="docutils literal"><span class="pre">GPGBase.binary</span></tt> is in a directory being removed, it +is linked to :<a class="reference external" href="file:'./gpg">file:’./gpg</a>‘ in the current directory.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>prog</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The program to remove from <tt class="docutils literal"><span class="pre">$PATH</span></tt>.</li> +<li><strong>at_exit</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – Add the program back into the <tt class="docutils literal"><span class="pre">$PATH</span></tt> when the +Python interpreter exits, and delete any symlinks +to <tt class="docutils literal"><span class="pre">GPGBase.binary</span></tt> which were created.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._meta.GPGBase.default_preference_list"> +<tt class="descname">default_preference_list</tt><a class="reference internal" href="_modules/gnupg/_meta.html#GPGBase.default_preference_list"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGBase.default_preference_list" title="Permalink to this definition">¶</a></dt> +<dd><p>Get the default preference list.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._meta.GPGBase.keyserver"> +<tt class="descname">keyserver</tt><a class="reference internal" href="_modules/gnupg/_meta.html#GPGBase.keyserver"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGBase.keyserver" title="Permalink to this definition">¶</a></dt> +<dd><p>Get the current keyserver setting.</p> +</dd></dl> + +<dl class="method"> +<dt id="gnupg._meta.GPGBase._homedir_getter"> +<tt class="descname">_homedir_getter</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/gnupg/_meta.html#GPGBase._homedir_getter"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGBase._homedir_getter" title="Permalink to this definition">¶</a></dt> +<dd><p>Get the directory currently being used as GnuPG’s homedir.</p> +<p>If unspecified, use <tt class="file docutils literal"><span class="pre">~/.config/python-gnupg/</span></tt></p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body">str</td> +</tr> +<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">The absolute path to the current GnuPG homedir.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg._meta.GPGBase._homedir_setter"> +<tt class="descname">_homedir_setter</tt><big>(</big><em>directory</em><big>)</big><a class="reference internal" href="_modules/gnupg/_meta.html#GPGBase._homedir_setter"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGBase._homedir_setter" title="Permalink to this definition">¶</a></dt> +<dd><p>Set the directory to use as GnuPG’s homedir.</p> +<p>If unspecified, use $HOME/.config/python-gnupg. If specified, ensure +that the <tt class="docutils literal"><span class="pre">directory</span></tt> does not contain various shell escape +characters. If <tt class="docutils literal"><span class="pre">directory</span></tt> is not found, it will be automatically +created. Lastly, the <tt class="docutils literal"><span class="pre">direcory</span></tt> will be checked that the EUID has +read and write permissions for it.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>directory</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – A relative or absolute path to the directory to +use for storing/accessing GnuPG’s files, including +keyrings and the trustdb.</td> +</tr> +<tr class="field-even field"><th class="field-name">Raises:</th><td class="field-body"><a class="reference external" href="http://docs.python.org/library/exceptions.html#exceptions.RuntimeError" title="(in Python v2.7)"><tt class="xref py py-exc docutils literal"><span class="pre">RuntimeError</span></tt></a> if unable to find a suitable +directory to use.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._meta.GPGBase.homedir"> +<tt class="descname">homedir</tt><a class="headerlink" href="#gnupg._meta.GPGBase.homedir" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="method"> +<dt id="gnupg._meta.GPGBase._generated_keys_getter"> +<tt class="descname">_generated_keys_getter</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/gnupg/_meta.html#GPGBase._generated_keys_getter"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGBase._generated_keys_getter" title="Permalink to this definition">¶</a></dt> +<dd><p>Get the <tt class="docutils literal"><span class="pre">homedir</span></tt> subdirectory for storing generated keys.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body">str</td> +</tr> +<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">The absolute path to the current GnuPG homedir.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg._meta.GPGBase._generated_keys_setter"> +<tt class="descname">_generated_keys_setter</tt><big>(</big><em>directory</em><big>)</big><a class="reference internal" href="_modules/gnupg/_meta.html#GPGBase._generated_keys_setter"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGBase._generated_keys_setter" title="Permalink to this definition">¶</a></dt> +<dd><p>Set the directory for storing generated keys.</p> +<p>If unspecified, use +<a class="reference internal" href="#gnupg._meta.GPGBase.homedir" title="gnupg._meta.GPGBase.homedir"><tt class="xref py py-meth docutils literal"><span class="pre">homedir()</span></tt></a>/generated-keys. If specified, +ensure that the <tt class="docutils literal"><span class="pre">directory</span></tt> does not contain various shell escape +characters. If <tt class="docutils literal"><span class="pre">directory</span></tt> isn’t found, it will be automatically +created. Lastly, the <tt class="docutils literal"><span class="pre">directory</span></tt> will be checked to ensure that the +current EUID has read and write permissions for it.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>directory</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – A relative or absolute path to the directory to +use for storing/accessing GnuPG’s files, including keyrings and +the trustdb.</td> +</tr> +<tr class="field-even field"><th class="field-name">Raises:</th><td class="field-body"><a class="reference external" href="http://docs.python.org/library/exceptions.html#exceptions.RuntimeError" title="(in Python v2.7)"><tt class="xref py py-exc docutils literal"><span class="pre">RuntimeError</span></tt></a> if unable to find a suitable +directory to use.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._meta.GPGBase._generated_keys"> +<tt class="descname">_generated_keys</tt><a class="headerlink" href="#gnupg._meta.GPGBase._generated_keys" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="method"> +<dt id="gnupg._meta.GPGBase._make_args"> +<tt class="descname">_make_args</tt><big>(</big><em>args</em>, <em>passphrase=False</em><big>)</big><a class="reference internal" href="_modules/gnupg/_meta.html#GPGBase._make_args"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGBase._make_args" title="Permalink to this definition">¶</a></dt> +<dd><p>Make a list of command line elements for GPG.</p> +<p>The value of <tt class="docutils literal"><span class="pre">args</span></tt> will be appended only if it passes the checks in +<a class="reference internal" href="#gnupg._parsers._sanitise" title="gnupg._parsers._sanitise"><tt class="xref py py-func docutils literal"><span class="pre">gnupg._parsers._sanitise()</span></tt></a>. The <tt class="docutils literal"><span class="pre">passphrase</span></tt> argument needs to +be True if a passphrase will be sent to GnuPG, else False.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>args</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#list" title="(in Python v2.7)"><em>list</em></a>) – A list of strings of options and flags to pass to +<tt class="docutils literal"><span class="pre">GPG.binary</span></tt>. This is input safe, meaning that +these values go through strict checks (see +<tt class="docutils literal"><span class="pre">parsers._sanitise_list</span></tt>) before being passed to to +the input file descriptor for the GnuPG process. +Each string should be given exactly as it would be on +the commandline interface to GnuPG, +e.g. [“–cipher-algo AES256”, “–default-key +A3ADB67A2CDB8B35”].</li> +<li><strong>passphrase</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, the passphrase will be sent to the +stdin file descriptor for the attached GnuPG +process.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg._meta.GPGBase._open_subprocess"> +<tt class="descname">_open_subprocess</tt><big>(</big><em>args=None</em>, <em>passphrase=False</em><big>)</big><a class="reference internal" href="_modules/gnupg/_meta.html#GPGBase._open_subprocess"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGBase._open_subprocess" title="Permalink to this definition">¶</a></dt> +<dd><p>Open a pipe to a GPG subprocess and return the file objects for +communicating with it.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>args</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#list" title="(in Python v2.7)"><em>list</em></a>) – A list of strings of options and flags to pass to +<tt class="docutils literal"><span class="pre">GPG.binary</span></tt>. This is input safe, meaning that +these values go through strict checks (see +<tt class="docutils literal"><span class="pre">parsers._sanitise_list</span></tt>) before being passed to to +the input file descriptor for the GnuPG process. +Each string should be given exactly as it would be on +the commandline interface to GnuPG, +e.g. [“–cipher-algo AES256”, “–default-key +A3ADB67A2CDB8B35”].</li> +<li><strong>passphrase</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, the passphrase will be sent to the +stdin file descriptor for the attached GnuPG +process.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg._meta.GPGBase._read_response"> +<tt class="descname">_read_response</tt><big>(</big><em>stream</em>, <em>result</em><big>)</big><a class="reference internal" href="_modules/gnupg/_meta.html#GPGBase._read_response"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGBase._read_response" title="Permalink to this definition">¶</a></dt> +<dd><p>Reads all the stderr output from GPG, taking notice only of lines +that begin with the magic [GNUPG:] prefix.</p> +<p>Calls methods on the response object for each valid token found, with +the arg being the remainder of the status line.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>stream</strong> – A byte-stream, file handle, or a +<a class="reference external" href="http://docs.python.org/library/subprocess.html#subprocess.PIPE" title="(in Python v2.7)"><tt class="xref py py-data docutils literal"><span class="pre">subprocess.PIPE</span></tt></a> for parsing the status codes +from the GnuPG process.</li> +<li><strong>result</strong> – The result parser class from <a class="reference internal" href="#module-gnupg._parsers" title="gnupg._parsers"><tt class="xref py py-mod docutils literal"><span class="pre">_parsers</span></tt></a> ― +the <tt class="docutils literal"><span class="pre">handle_status()</span></tt> method of that class will be +called in order to parse the output of <tt class="docutils literal"><span class="pre">stream</span></tt>.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg._meta.GPGBase._read_data"> +<tt class="descname">_read_data</tt><big>(</big><em>stream</em>, <em>result</em><big>)</big><a class="reference internal" href="_modules/gnupg/_meta.html#GPGBase._read_data"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGBase._read_data" title="Permalink to this definition">¶</a></dt> +<dd><p>Incrementally read from <tt class="docutils literal"><span class="pre">stream</span></tt> and store read data.</p> +<p>All data gathered from calling <tt class="docutils literal"><span class="pre">stream.read()</span></tt> will be concatenated +and stored as <tt class="docutils literal"><span class="pre">result.data</span></tt>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>stream</strong> – An open file-like object to read() from.</li> +<li><strong>result</strong> – An instance of one of the <a class="reference internal" href="#parsers"><em>result parsing classes</em></a> from <tt class="xref py py-const docutils literal"><span class="pre">_result_map</span></tt>.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg._meta.GPGBase._collect_output"> +<tt class="descname">_collect_output</tt><big>(</big><em>process</em>, <em>result</em>, <em>writer=None</em>, <em>stdin=None</em><big>)</big><a class="reference internal" href="_modules/gnupg/_meta.html#GPGBase._collect_output"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGBase._collect_output" title="Permalink to this definition">¶</a></dt> +<dd><p>Drain the subprocesses output streams, writing the collected output +to the result. If a writer thread (writing to the subprocess) is given, +make sure it’s joined before returning. If a stdin stream is given, +close it before returning.</p> +</dd></dl> + +<dl class="method"> +<dt id="gnupg._meta.GPGBase._handle_io"> +<tt class="descname">_handle_io</tt><big>(</big><em>args</em>, <em>file</em>, <em>result</em>, <em>passphrase=False</em>, <em>binary=False</em><big>)</big><a class="reference internal" href="_modules/gnupg/_meta.html#GPGBase._handle_io"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGBase._handle_io" title="Permalink to this definition">¶</a></dt> +<dd><p>Handle a call to GPG - pass input data, collect output data.</p> +</dd></dl> + +<dl class="method"> +<dt id="gnupg._meta.GPGBase._recv_keys"> +<tt class="descname">_recv_keys</tt><big>(</big><em>keyids</em>, <em>keyserver=None</em><big>)</big><a class="reference internal" href="_modules/gnupg/_meta.html#GPGBase._recv_keys"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGBase._recv_keys" title="Permalink to this definition">¶</a></dt> +<dd><p>Import keys from a keyserver.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>keyids</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – A space-delimited string containing the keyids to +request.</li> +<li><strong>keyserver</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The keyserver to request the <tt class="docutils literal"><span class="pre">keyids</span></tt> from; +defaults to <cite>gnupg.GPG.keyserver</cite>.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg._meta.GPGBase._sign_file"> +<tt class="descname">_sign_file</tt><big>(</big><em>file</em>, <em>default_key=None</em>, <em>passphrase=None</em>, <em>clearsign=True</em>, <em>detach=False</em>, <em>binary=False</em>, <em>digest_algo='SHA512'</em><big>)</big><a class="reference internal" href="_modules/gnupg/_meta.html#GPGBase._sign_file"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGBase._sign_file" title="Permalink to this definition">¶</a></dt> +<dd><p>Create a signature for a file.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>file</strong> – The file stream (i.e. it’s already been open()’d) to sign.</li> +<li><strong>default_key</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The key to sign with.</li> +<li><strong>passphrase</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The passphrase to pipe to stdin.</li> +<li><strong>clearsign</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, create a cleartext signature.</li> +<li><strong>detach</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, create a detached signature.</li> +<li><strong>binary</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, do not ascii armour the output.</li> +<li><strong>digest_algo</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The hash digest to use. Again, to see which +hashes your GnuPG is capable of using, do: +<tt class="docutils literal"><span class="pre">$</span> <span class="pre">gpg</span> <span class="pre">--with-colons</span> <span class="pre">--list-config</span> +<span class="pre">digestname</span></tt>. The default, if unspecified, is +<tt class="docutils literal"><span class="pre">'SHA512'</span></tt>.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg._meta.GPGBase._encrypt"> +<tt class="descname">_encrypt</tt><big>(</big><em>data</em>, <em>recipients</em>, <em>default_key=None</em>, <em>passphrase=None</em>, <em>armor=True</em>, <em>encrypt=True</em>, <em>symmetric=False</em>, <em>always_trust=True</em>, <em>output=None</em>, <em>cipher_algo='AES256'</em>, <em>digest_algo='SHA512'</em>, <em>compress_algo='ZLIB'</em><big>)</big><a class="reference internal" href="_modules/gnupg/_meta.html#GPGBase._encrypt"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._meta.GPGBase._encrypt" title="Permalink to this definition">¶</a></dt> +<dd><p>Encrypt the message read from the file-like object <strong>data</strong>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>data</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The file or bytestream to encrypt.</li> +<li><strong>recipients</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The recipients to encrypt to. Recipients must +be specified keyID/fingerprint.</li> +</ul> +</td> +</tr> +</tbody> +</table> +<div class="admonition warning"> +<p class="first admonition-title">Warning</p> +<p class="last">Care should be taken in Python2 to make sure that the +given fingerprints for <strong>recipients</strong> are in fact strings +and not unicode objects.</p> +</div> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>default_key</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The keyID/fingerprint of the key to use for +signing. If given, <strong>data</strong> will be encrypted +<em>and</em> signed.</li> +<li><strong>passphrase</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – If given, and <strong>default_key</strong> is also given, +use this passphrase to unlock the secret +portion of the <strong>default_key</strong> to sign the +encrypted <strong>data</strong>. Otherwise, if +<strong>default_key</strong> is not given, but <strong>symmetric</strong> +is <tt class="docutils literal"><span class="pre">True</span></tt>, then use this passphrase as the +passphrase for symmetric encryption. Signing +and symmetric encryption should <em>not</em> be +combined when sending the <strong>data</strong> to other +recipients, else the passphrase to the secret +key would be shared with them.</li> +<li><strong>armor</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, ascii armor the output; otherwise, the +output will be in binary format. (Default: True)</li> +<li><strong>encrypt</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, encrypt the <strong>data</strong> using the +<strong>recipients</strong> public keys. (Default: True)</li> +<li><strong>symmetric</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, encrypt the <strong>data</strong> to <strong>recipients</strong> +using a symmetric key. See the <strong>passphrase</strong> +parameter. Symmetric encryption and public key +encryption can be used simultaneously, and will +result in a ciphertext which is decryptable +with either the symmetric <strong>passphrase</strong> or one +of the corresponding private keys.</li> +<li><strong>always_trust</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, ignore trust warnings on +<strong>recipients</strong> keys. If False, display trust +warnings. (default: True)</li> +<li><strong>output</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The output file to write to. If not specified, the +encrypted output is returned, and thus should be +stored as an object in Python. For example:</li> +</ul> +</td> +</tr> +</tbody> +</table> +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">shutil</span> +<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">gnupg</span> +<span class="gp">>>> </span><span class="k">if</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">exists</span><span class="p">(</span><span class="s">"doctests"</span><span class="p">):</span> +<span class="gp">... </span> <span class="n">shutil</span><span class="o">.</span><span class="n">rmtree</span><span class="p">(</span><span class="s">"doctests"</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">gpg</span> <span class="o">=</span> <span class="n">gnupg</span><span class="o">.</span><span class="n">GPG</span><span class="p">(</span><span class="n">homedir</span><span class="o">=</span><span class="s">"doctests"</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">key_settings</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">gen_key_input</span><span class="p">(</span><span class="n">key_type</span><span class="o">=</span><span class="s">'RSA'</span><span class="p">,</span> +<span class="gp">... </span> <span class="n">key_length</span><span class="o">=</span><span class="mi">1024</span><span class="p">,</span> +<span class="gp">... </span> <span class="n">key_usage</span><span class="o">=</span><span class="s">'ESCA'</span><span class="p">,</span> +<span class="gp">... </span> <span class="n">passphrase</span><span class="o">=</span><span class="s">'foo'</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">key</span> <span class="o">=</span> <span class="n">gpg</span><span class="o">.</span><span class="n">gen_key</span><span class="p">(</span><span class="n">key_settings</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">message</span> <span class="o">=</span> <span class="s">"The crow flies at midnight."</span> +<span class="gp">>>> </span><span class="n">encrypted</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">gpg</span><span class="o">.</span><span class="n">encrypt</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">key</span><span class="o">.</span><span class="n">printprint</span><span class="p">))</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">encrypted</span> <span class="o">!=</span> <span class="n">message</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="ow">not</span> <span class="n">encrypted</span><span class="o">.</span><span class="n">isspace</span><span class="p">()</span> +<span class="gp">>>> </span><span class="n">decrypted</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">gpg</span><span class="o">.</span><span class="n">decrypt</span><span class="p">(</span><span class="n">encrypted</span><span class="p">))</span> +<span class="gp">>>> </span><span class="k">assert</span> <span class="ow">not</span> <span class="n">decrypted</span><span class="o">.</span><span class="n">isspace</span><span class="p">()</span> +<span class="gp">>>> </span><span class="n">decrypted</span> +<span class="go">'The crow flies at midnight.'</span> +</pre></div> +</div> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>cipher_algo</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The cipher algorithm to use. To see available +algorithms with your version of GnuPG, do: +<strong class="command">$ gpg –with-colons –list-config +ciphername</strong>. The default <strong>cipher_algo</strong>, if +unspecified, is <tt class="docutils literal"><span class="pre">'AES256'</span></tt>.</li> +<li><strong>digest_algo</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The hash digest to use. Again, to see which +hashes your GnuPG is capable of using, do: +<strong class="command">$ gpg –with-colons –list-config +digestname</strong>. The default, if unspecified, is +<tt class="docutils literal"><span class="pre">'SHA512'</span></tt>.</li> +<li><strong>compress_algo</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The compression algorithm to use. Can be one +of <tt class="docutils literal"><span class="pre">'ZLIB'</span></tt>, <tt class="docutils literal"><span class="pre">'BZIP2'</span></tt>, <tt class="docutils literal"><span class="pre">'ZIP'</span></tt>, or +<tt class="docutils literal"><span class="pre">'Uncompressed'</span></tt>.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +</dd></dl> + +</div> +<div class="section" id="parsers-module"> +<span id="parsers"></span><h2>parsers module<a class="headerlink" href="#parsers-module" title="Permalink to this headline">¶</a></h2> +<p>These are classes for parsing both user inputs and status file descriptor +flags from GnuPG’s output. The latter are used in order to determine what our +GnuPG process is doing and retrieve information about its operations, which +are stored in corresponding classes in +<tt class="xref py py-attr docutils literal"><span class="pre">_result_map</span></tt>. Some status flags aren’t handled yet +– information on <em>all</em> of the flags (well, at least the documented ones…) can +be found in the <tt class="file docutils literal"><span class="pre">docs/DETAILS</span></tt> file in GnuPG’s <a class="reference external" href="http://http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=shortlog;h=refs/heads/master">source</a>, which has been +included <a class="reference external" href="./_static/DETAILS.html">here</a> as well.</p> +<span class="target" id="module-gnupg._parsers"></span><p>Classes for parsing GnuPG status messages and sanitising commandline +options.</p> +<dl class="exception"> +<dt id="gnupg._parsers.ProtectedOption"> +<em class="property">exception </em><tt class="descname">ProtectedOption</tt><a class="reference internal" href="_modules/gnupg/_parsers.html#ProtectedOption"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.ProtectedOption" title="Permalink to this definition">¶</a></dt> +<dd><p>Bases: <a class="reference external" href="http://docs.python.org/library/exceptions.html#exceptions.Exception" title="(in Python v2.7)"><tt class="xref py py-class docutils literal"><span class="pre">exceptions.Exception</span></tt></a></p> +<p>Raised when the option passed to GPG is disallowed.</p> +</dd></dl> + +<dl class="exception"> +<dt id="gnupg._parsers.UsageError"> +<em class="property">exception </em><tt class="descname">UsageError</tt><a class="reference internal" href="_modules/gnupg/_parsers.html#UsageError"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.UsageError" title="Permalink to this definition">¶</a></dt> +<dd><p>Bases: <a class="reference external" href="http://docs.python.org/library/exceptions.html#exceptions.Exception" title="(in Python v2.7)"><tt class="xref py py-class docutils literal"><span class="pre">exceptions.Exception</span></tt></a></p> +<p>Raised when incorrect usage of the API occurs..</p> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._parsers._check_keyserver"> +<tt class="descname">_check_keyserver</tt><big>(</big><em>location</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#_check_keyserver"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers._check_keyserver" title="Permalink to this definition">¶</a></dt> +<dd><p>Check that a given keyserver is a known protocol and does not contain +shell escape characters.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>location</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – A string containing the default keyserver. This +should contain the desired keyserver protocol which +is supported by the keyserver, for example, the +default is <tt class="docutils literal"><span class="pre">'hkp://wwwkeys</span> <span class="pre">.pgp.net'</span></tt>.</td> +</tr> +<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body"><a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><tt class="xref py py-obj docutils literal"><span class="pre">str</span></tt></a> or <a class="reference external" href="http://docs.python.org/library/constants.html#None" title="(in Python v2.7)"><tt class="xref py py-obj docutils literal"><span class="pre">None</span></tt></a></td> +</tr> +<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">A string specifying the protocol and keyserver hostname, if the +checks passed. If not, returns None.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._parsers._check_preferences"> +<tt class="descname">_check_preferences</tt><big>(</big><em>prefs</em>, <em>pref_type=None</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#_check_preferences"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers._check_preferences" title="Permalink to this definition">¶</a></dt> +<dd><p>Check cipher, digest, and compression preference settings.</p> +<p>MD5 is not allowed. This is <a class="reference external" href="http://www.cs.colorado.edu/~jrblack/papers/md5e-full.pdf">not 1994</a>. SHA1 is <a class="reference external" href="http://eprint.iacr.org/2008/469.pdf">allowed</a> <a class="reference external" href="https://www.schneier.com/blog/archives/2012/10/when_will_we_se.html">grudgingly</a>.</p> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._parsers._fix_unsafe"> +<tt class="descname">_fix_unsafe</tt><big>(</big><em>shell_input</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#_fix_unsafe"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers._fix_unsafe" title="Permalink to this definition">¶</a></dt> +<dd><p>Find characters used to escape from a string into a shell, and wrap them in +quotes if they exist. Regex pilfered from Python3 <a class="reference external" href="http://docs.python.org/library/shlex.html#module-shlex" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">shlex</span></tt></a> module.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>shell_input</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The input intended for the GnuPG process.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._parsers._hyphenate"> +<tt class="descname">_hyphenate</tt><big>(</big><em>input</em>, <em>add_prefix=False</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#_hyphenate"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers._hyphenate" title="Permalink to this definition">¶</a></dt> +<dd><p>Change underscores to hyphens so that object attributes can be easily +tranlated to GPG option names.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><strong>input</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The attribute to hyphenate.</li> +<li><strong>add_prefix</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, add leading hyphens to the input.</li> +</ul> +</td> +</tr> +<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body"><p class="first">str</p> +</td> +</tr> +<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">The <tt class="docutils literal"><span class="pre">input</span></tt> with underscores changed to hyphens.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._parsers._is_allowed"> +<tt class="descname">_is_allowed</tt><big>(</big><em>input</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#_is_allowed"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers._is_allowed" title="Permalink to this definition">¶</a></dt> +<dd><p>Check that an option or argument given to GPG is in the set of allowed +options, the latter being a strict subset of the set of all options known +to GPG.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>input</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – An input meant to be parsed as an option or flag to the +GnuPG process. Should be formatted the same as an option +or flag to the commandline gpg, i.e. “–encrypt-files”.</p> +</td> +</tr> +<tr class="field-even field"><th class="field-name">Variables:</th><td class="field-body"><ul class="first simple"> +<li><strong>gnupg_options</strong> (<a class="reference external" href="http://docs.python.org/library/stdtypes.html#frozenset" title="(in Python v2.7)"><em>frozenset</em></a>) – All known GPG options and flags.</li> +<li><strong>allowed</strong> (<a class="reference external" href="http://docs.python.org/library/stdtypes.html#frozenset" title="(in Python v2.7)"><em>frozenset</em></a>) – All allowed GPG options and flags, e.g. all GPG +options and flags which we are willing to +acknowledge and parse. If we want to support a +new option, it will need to have its own parsing +class and its name will need to be added to this +set.</li> +</ul> +</td> +</tr> +<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><p class="first"><a class="reference internal" href="#gnupg._parsers.UsageError" title="gnupg._parsers.UsageError"><tt class="xref py py-exc docutils literal"><span class="pre">UsageError</span></tt></a> if <strong>input</strong> is not a subset of the hard-coded +set of all GnuPG options in <a class="reference internal" href="#gnupg._parsers._get_all_gnupg_options" title="gnupg._parsers._get_all_gnupg_options"><tt class="xref py py-func docutils literal"><span class="pre">_get_all_gnupg_options()</span></tt></a>.</p> +<p><a class="reference internal" href="#gnupg._parsers.ProtectedOption" title="gnupg._parsers.ProtectedOption"><tt class="xref py py-exc docutils literal"><span class="pre">ProtectedOption</span></tt></a> if <strong>input</strong> is not in the set of allowed +options.</p> +</td> +</tr> +<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body"><p class="first">str</p> +</td> +</tr> +<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">The original <strong>input</strong> parameter, unmodified and unsanitized, if +no errors occur.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._parsers._is_hex"> +<tt class="descname">_is_hex</tt><big>(</big><em>string</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#_is_hex"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers._is_hex" title="Permalink to this definition">¶</a></dt> +<dd><p>Check that a string is hexidecimal, with alphabetic characters +capitalized and without whitespace.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>string</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The string to check.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._parsers._is_string"> +<tt class="descname">_is_string</tt><big>(</big><em>thing</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#_is_string"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers._is_string" title="Permalink to this definition">¶</a></dt> +<dd><p>Python character arrays are a mess.</p> +<p>If Python2, check if <strong>thing</strong> is an <a class="reference external" href="http://docs.python.org/library/functions.html#unicode" title="(in Python v2.7)"><tt class="xref py py-obj docutils literal"><span class="pre">unicode</span></tt></a> or a <a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><tt class="xref py py-obj docutils literal"><span class="pre">str</span></tt></a>. +If Python3, check if <strong>thing</strong> is a <a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><tt class="xref py py-obj docutils literal"><span class="pre">str</span></tt></a>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>thing</strong> – The thing to check.</td> +</tr> +<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">True</span></tt> if <strong>thing</strong> is a string according to whichever version +of Python we’re running in.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._parsers._sanitise"> +<tt class="descname">_sanitise</tt><big>(</big><em>*args</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#_sanitise"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers._sanitise" title="Permalink to this definition">¶</a></dt> +<dd><p>Take an arg or the key portion of a kwarg and check that it is in the +set of allowed GPG options and flags, and that it has the correct +type. Then, attempt to escape any unsafe characters. If an option is not +allowed, drop it with a logged warning. Returns a dictionary of all +sanitised, allowed options.</p> +<p>Each new option that we support that is not a boolean, but instead has +some additional inputs following it, i.e. “–encrypt-file foo.txt”, will +need some basic safety checks added here.</p> +<p>GnuPG has three-hundred and eighteen commandline flags. Also, not all +implementations of OpenPGP parse PGP packets and headers in the same way, +so there is added potential there for messing with calls to GPG.</p> +<p>For information on the PGP message format specification, see +<span class="target" id="index-0"></span><a class="rfc reference external" href="http://tools.ietf.org/html/rfc1991.html"><strong>RFC 1991</strong></a>.</p> +<p>If you’re asking, “Is this <em>really</em> necessary?”: No, not really – we could +just follow the security precautions recommended by <a class="reference external" href="https://xkcd.com/1181/">this xkcd</a>.</p> +<blockquote> +<div></div></blockquote> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>args</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – (optional) The boolean arguments which will be passed to +the GnuPG process.</td> +</tr> +<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body">str</td> +</tr> +<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">sanitised</span></tt></td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._parsers._sanitise_list"> +<tt class="descname">_sanitise_list</tt><big>(</big><em>arg_list</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#_sanitise_list"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers._sanitise_list" title="Permalink to this definition">¶</a></dt> +<dd><p>A generator for iterating through a list of gpg options and sanitising +them.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>arg_list</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#list" title="(in Python v2.7)"><em>list</em></a>) – A list of options and flags for GnuPG.</td> +</tr> +<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body">generator</td> +</tr> +<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">A generator whose next() method returns each of the items in +<tt class="docutils literal"><span class="pre">arg_list</span></tt> after calling <tt class="docutils literal"><span class="pre">_sanitise()</span></tt> with that item as a +parameter.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._parsers._get_options_group"> +<tt class="descname">_get_options_group</tt><big>(</big><em>group=None</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#_get_options_group"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers._get_options_group" title="Permalink to this definition">¶</a></dt> +<dd><p>Get a specific group of options which are allowed.</p> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._parsers._get_all_gnupg_options"> +<tt class="descname">_get_all_gnupg_options</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#_get_all_gnupg_options"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers._get_all_gnupg_options" title="Permalink to this definition">¶</a></dt> +<dd><p>Get all GnuPG options and flags.</p> +<p>This is hardcoded within a local scope to reduce the chance of a tampered +GnuPG binary reporting falsified option sets, i.e. because certain options +(namedly the <tt class="docutils literal"><span class="pre">--no-options</span></tt> option, which prevents the usage of gpg.conf +files) are necessary and statically specified in +<a class="reference internal" href="#gnupg._meta.GPGBase._make_args" title="gnupg._meta.GPGBase._make_args"><tt class="xref py py-meth docutils literal"><span class="pre">gnupg._meta.GPGBase._make_args()</span></tt></a>, if the inputs into Python are +already controlled, and we were to summon the GnuPG binary to ask it for +its options, it would be possible to receive a falsified options set +missing the <tt class="docutils literal"><span class="pre">--no-options</span></tt> option in response. This seems unlikely, and +the method is stupid and ugly, but at least we’ll never have to debug +whether or not an option <em>actually</em> disappeared in a different GnuPG +version, or some funny business is happening.</p> +<p>These are the options as of GnuPG 1.4.12; the current stable branch of the +2.1.x tree contains a few more – if you need them you’ll have to add them +in here.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Variables:</th><td class="field-body"><strong>gnupg_options</strong> – All known GPG options and flags.</td> +</tr> +<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body">frozenset</td> +</tr> +<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">gnupg_options</span></tt></td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._parsers.nodata"> +<tt class="descname">nodata</tt><big>(</big><em>status_code</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#nodata"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.nodata" title="Permalink to this definition">¶</a></dt> +<dd><p>Translate NODATA status codes from GnuPG to messages.</p> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._parsers.progress"> +<tt class="descname">progress</tt><big>(</big><em>status_code</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#progress"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.progress" title="Permalink to this definition">¶</a></dt> +<dd><p>Translate PROGRESS status codes from GnuPG to messages.</p> +</dd></dl> + +<dl class="class"> +<dt id="gnupg._parsers.GenKey"> +<em class="property">class </em><tt class="descname">GenKey</tt><big>(</big><em>gpg</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#GenKey"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.GenKey" title="Permalink to this definition">¶</a></dt> +<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></p> +<p>Handle status messages for key generation.</p> +<p>Calling the <tt class="docutils literal"><span class="pre">__str__()</span></tt> method of this class will return the generated +key’s fingerprint, or a status string explaining the results.</p> +<dl class="attribute"> +<dt id="gnupg._parsers.GenKey.type"> +<tt class="descname">type</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.GenKey.type" title="Permalink to this definition">¶</a></dt> +<dd><p>‘P’:= primary, ‘S’:= subkey, ‘B’:= both</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.GenKey.keyring"> +<tt class="descname">keyring</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.GenKey.keyring" title="Permalink to this definition">¶</a></dt> +<dd><p>This will store the key’s public keyring filename, if +<a class="reference internal" href="#gnupg.GPG.gen_key_input" title="gnupg.GPG.gen_key_input"><tt class="xref py py-meth docutils literal"><span class="pre">gen_key_input()</span></tt></a> was called with +<tt class="docutils literal"><span class="pre">separate_keyring=True</span></tt>.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.GenKey.secring"> +<tt class="descname">secring</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.GenKey.secring" title="Permalink to this definition">¶</a></dt> +<dd><p>This will store the key’s secret keyring filename, if : +<a class="reference internal" href="#gnupg.GPG.gen_key_input" title="gnupg.GPG.gen_key_input"><tt class="xref py py-meth docutils literal"><span class="pre">gen_key_input()</span></tt></a> was called with +<tt class="docutils literal"><span class="pre">separate_keyring=True</span></tt>.</p> +</dd></dl> + +<dl class="method"> +<dt id="gnupg._parsers.GenKey._handle_status"> +<tt class="descname">_handle_status</tt><big>(</big><em>key</em>, <em>value</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#GenKey._handle_status"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.GenKey._handle_status" title="Permalink to this definition">¶</a></dt> +<dd><p>Parse a status code from the attached GnuPG process.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><a class="reference external" href="http://docs.python.org/library/exceptions.html#exceptions.ValueError" title="(in Python v2.7)"><tt class="xref py py-exc docutils literal"><span class="pre">ValueError</span></tt></a> if the status message is unknown.</td> +</tr> +</tbody> +</table> +</dd></dl> + +</dd></dl> + +<dl class="class"> +<dt id="gnupg._parsers.DeleteResult"> +<em class="property">class </em><tt class="descname">DeleteResult</tt><big>(</big><em>gpg</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#DeleteResult"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.DeleteResult" title="Permalink to this definition">¶</a></dt> +<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></p> +<p>Handle status messages for –delete-keys and –delete-secret-keys</p> +<dl class="attribute"> +<dt id="gnupg._parsers.DeleteResult.problem_reason"> +<tt class="descname">problem_reason</tt><em class="property"> = {'1': 'No such key', '3': 'Ambigious specification', '2': 'Must delete secret key first'}</em><a class="headerlink" href="#gnupg._parsers.DeleteResult.problem_reason" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="method"> +<dt id="gnupg._parsers.DeleteResult._handle_status"> +<tt class="descname">_handle_status</tt><big>(</big><em>key</em>, <em>value</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#DeleteResult._handle_status"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.DeleteResult._handle_status" title="Permalink to this definition">¶</a></dt> +<dd><p>Parse a status code from the attached GnuPG process.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><a class="reference external" href="http://docs.python.org/library/exceptions.html#exceptions.ValueError" title="(in Python v2.7)"><tt class="xref py py-exc docutils literal"><span class="pre">ValueError</span></tt></a> if the status message is unknown.</td> +</tr> +</tbody> +</table> +</dd></dl> + +</dd></dl> + +<dl class="class"> +<dt id="gnupg._parsers.Sign"> +<em class="property">class </em><tt class="descname">Sign</tt><big>(</big><em>gpg</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#Sign"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.Sign" title="Permalink to this definition">¶</a></dt> +<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></p> +<p>Parse GnuPG status messages for signing operations.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>gpg</strong> – An instance of <a class="reference internal" href="#gnupg.GPG" title="gnupg.GPG"><tt class="xref py py-class docutils literal"><span class="pre">gnupg.GPG</span></tt></a>.</td> +</tr> +</tbody> +</table> +<dl class="attribute"> +<dt id="gnupg._parsers.Sign.sig_type"> +<tt class="descname">sig_type</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Sign.sig_type" title="Permalink to this definition">¶</a></dt> +<dd><p>The type of signature created.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Sign.sig_algo"> +<tt class="descname">sig_algo</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Sign.sig_algo" title="Permalink to this definition">¶</a></dt> +<dd><p>The algorithm used to create the signature.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Sign.sig_hash_also"> +<tt class="descname">sig_hash_also</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Sign.sig_hash_also" title="Permalink to this definition">¶</a></dt> +<dd><p>The hash algorithm used to create the signature.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Sign.fingerprint"> +<tt class="descname">fingerprint</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Sign.fingerprint" title="Permalink to this definition">¶</a></dt> +<dd><p>The fingerprint of the signing keyid.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Sign.timestamp"> +<tt class="descname">timestamp</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Sign.timestamp" title="Permalink to this definition">¶</a></dt> +<dd><p>The timestamp on the signature.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Sign.what"> +<tt class="descname">what</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Sign.what" title="Permalink to this definition">¶</a></dt> +<dd><p>xxx fill me in</p> +</dd></dl> + +<dl class="method"> +<dt id="gnupg._parsers.Sign._handle_status"> +<tt class="descname">_handle_status</tt><big>(</big><em>key</em>, <em>value</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#Sign._handle_status"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.Sign._handle_status" title="Permalink to this definition">¶</a></dt> +<dd><p>Parse a status code from the attached GnuPG process.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><a class="reference external" href="http://docs.python.org/library/exceptions.html#exceptions.ValueError" title="(in Python v2.7)"><tt class="xref py py-exc docutils literal"><span class="pre">ValueError</span></tt></a> if the status message is unknown.</td> +</tr> +</tbody> +</table> +</dd></dl> + +</dd></dl> + +<dl class="class"> +<dt id="gnupg._parsers.ListKeys"> +<em class="property">class </em><tt class="descname">ListKeys</tt><big>(</big><em>gpg</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#ListKeys"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.ListKeys" title="Permalink to this definition">¶</a></dt> +<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">list</span></tt></p> +<p>Handle status messages for –list-keys.</p> +<p>Handles pub and uid (relating the latter to the former). Don’t care about +the following attributes/status messages (from doc/DETAILS):</p> +<div class="line-block"> +<div class="line">crt = X.509 certificate</div> +<div class="line">crs = X.509 certificate and private key available</div> +<div class="line">ssb = secret subkey (secondary key)</div> +<div class="line">uat = user attribute (same as user id except for field 10).</div> +<div class="line">sig = signature</div> +<div class="line">rev = revocation signature</div> +<div class="line">pkd = public key data (special field format, see below)</div> +<div class="line">grp = reserved for gpgsm</div> +<div class="line">rvk = revocation key</div> +</div> +<dl class="method"> +<dt id="gnupg._parsers.ListKeys.key"> +<tt class="descname">key</tt><big>(</big><em>args</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#ListKeys.key"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.ListKeys.key" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="method"> +<dt id="gnupg._parsers.ListKeys.pub"> +<tt class="descname">pub</tt><big>(</big><em>args</em><big>)</big><a class="headerlink" href="#gnupg._parsers.ListKeys.pub" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="method"> +<dt id="gnupg._parsers.ListKeys.sec"> +<tt class="descname">sec</tt><big>(</big><em>args</em><big>)</big><a class="headerlink" href="#gnupg._parsers.ListKeys.sec" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="method"> +<dt id="gnupg._parsers.ListKeys.fpr"> +<tt class="descname">fpr</tt><big>(</big><em>args</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#ListKeys.fpr"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.ListKeys.fpr" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="method"> +<dt id="gnupg._parsers.ListKeys.uid"> +<tt class="descname">uid</tt><big>(</big><em>args</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#ListKeys.uid"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.ListKeys.uid" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="method"> +<dt id="gnupg._parsers.ListKeys.sub"> +<tt class="descname">sub</tt><big>(</big><em>args</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#ListKeys.sub"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.ListKeys.sub" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="method"> +<dt id="gnupg._parsers.ListKeys._handle_status"> +<tt class="descname">_handle_status</tt><big>(</big><em>key</em>, <em>value</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#ListKeys._handle_status"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.ListKeys._handle_status" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +</dd></dl> + +<dl class="class"> +<dt id="gnupg._parsers.ImportResult"> +<em class="property">class </em><tt class="descname">ImportResult</tt><big>(</big><em>gpg</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#ImportResult"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.ImportResult" title="Permalink to this definition">¶</a></dt> +<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></p> +<p>Parse GnuPG status messages for key import operations.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>gpg</strong> (<a class="reference internal" href="#gnupg.GPG" title="gnupg.GPG"><tt class="xref py py-class docutils literal"><span class="pre">gnupg.GPG</span></tt></a>) – An instance of <a class="reference internal" href="#gnupg.GPG" title="gnupg.GPG"><tt class="xref py py-class docutils literal"><span class="pre">gnupg.GPG</span></tt></a>.</td> +</tr> +</tbody> +</table> +<dl class="attribute"> +<dt id="gnupg._parsers.ImportResult._ok_reason"> +<tt class="descname">_ok_reason</tt><em class="property"> = {'17': 'Contains private key', '16': 'Contains private key', '1': 'Entirely new key', '0': 'Not actually changed', '2': 'New user IDs', '4': 'New signatures', '8': 'New subkeys'}</em><a class="headerlink" href="#gnupg._parsers.ImportResult._ok_reason" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.ImportResult._problem_reason"> +<tt class="descname">_problem_reason</tt><em class="property"> = {'1': 'Invalid Certificate', '0': 'No specific reason given', '3': 'Certificate Chain too long', '2': 'Issuer Certificate missing', '4': 'Error storing certificate'}</em><a class="headerlink" href="#gnupg._parsers.ImportResult._problem_reason" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.ImportResult._fields"> +<tt class="descname">_fields</tt><em class="property"> = ['count', 'no_user_id', 'imported', 'imported_rsa', 'unchanged', 'n_uids', 'n_subk', 'n_sigs', 'n_revoc', 'sec_read', 'sec_imported', 'sec_dups', 'not_imported']</em><a class="headerlink" href="#gnupg._parsers.ImportResult._fields" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.ImportResult._counts"> +<tt class="descname">_counts</tt><em class="property"> = OrderedDict([('count', 0), ('no_user_id', 0), ('imported', 0), ('imported_rsa', 0), ('unchanged', 0), ('n_uids', 0), ('n_subk', 0), ('n_sigs', 0), ('n_revoc', 0), ('sec_read', 0), ('sec_imported', 0), ('sec_dups', 0), ('not_imported', 0)])</em><a class="headerlink" href="#gnupg._parsers.ImportResult._counts" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.ImportResult.fingerprints"> +<tt class="descname">fingerprints</tt><em class="property"> = []</em><a class="headerlink" href="#gnupg._parsers.ImportResult.fingerprints" title="Permalink to this definition">¶</a></dt> +<dd><p>A list of strings containing the fingerprints of the GnuPG keyIDs +imported.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.ImportResult.results"> +<tt class="descname">results</tt><em class="property"> = []</em><a class="headerlink" href="#gnupg._parsers.ImportResult.results" title="Permalink to this definition">¶</a></dt> +<dd><p>A list containing dictionaries with information gathered on keys +imported.</p> +</dd></dl> + +<dl class="method"> +<dt id="gnupg._parsers.ImportResult._handle_status"> +<tt class="descname">_handle_status</tt><big>(</big><em>key</em>, <em>value</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#ImportResult._handle_status"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.ImportResult._handle_status" title="Permalink to this definition">¶</a></dt> +<dd><p>Parse a status code from the attached GnuPG process.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><a class="reference external" href="http://docs.python.org/library/exceptions.html#exceptions.ValueError" title="(in Python v2.7)"><tt class="xref py py-exc docutils literal"><span class="pre">ValueError</span></tt></a> if the status message is unknown.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="gnupg._parsers.ImportResult.summary"> +<tt class="descname">summary</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#ImportResult.summary"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.ImportResult.summary" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.ImportResult.x"> +<tt class="descname">x</tt><em class="property"> = 12</em><a class="headerlink" href="#gnupg._parsers.ImportResult.x" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +</dd></dl> + +<dl class="class"> +<dt id="gnupg._parsers.Verify"> +<em class="property">class </em><tt class="descname">Verify</tt><big>(</big><em>gpg</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#Verify"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.Verify" title="Permalink to this definition">¶</a></dt> +<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></p> +<p>Parser for status messages from GnuPG for certifications and signature +verifications.</p> +<p>People often mix these up, or think that they are the same thing. While it +is true that certifications and signatures <em>are</em> the same cryptographic +operation – and also true that both are the same as the decryption +operation – a distinction is made for important reasons.</p> +<dl class="docutils"> +<dt>A certification:</dt> +<dd><ul class="first last simple"> +<li>is made on a key,</li> +<li>can help to validate or invalidate the key owner’s identity,</li> +<li>can assign trust levels to the key (or to uids and/or subkeys that +the key contains),</li> +<li>and can be used in absense of in-person fingerprint checking to try +to build a path (through keys whose fingerprints have been checked) +to the key, so that the identity of the key’s owner can be more +reliable without having to actually physically meet in person.</li> +</ul> +</dd> +<dt>A signature:</dt> +<dd><ul class="first last simple"> +<li>is created for a file or other piece of data,</li> +<li>can help to prove that the data hasn’t been altered,</li> +<li>and can help to prove that the data was sent by the person(s) in +possession of the private key that created the signature, and for +parsing portions of status messages from decryption operations.</li> +</ul> +</dd> +</dl> +<p>There are probably other things unique to each that have been +scatterbrainedly omitted due to the programmer sitting still and staring +at GnuPG debugging logs for too long without snacks, but that is the gist +of it.</p> +<p>Create a parser for verification and certification commands.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>gpg</strong> – An instance of <a class="reference internal" href="#gnupg.GPG" title="gnupg.GPG"><tt class="xref py py-class docutils literal"><span class="pre">gnupg.GPG</span></tt></a>.</td> +</tr> +</tbody> +</table> +<dl class="attribute"> +<dt id="gnupg._parsers.Verify.TRUST_UNDEFINED"> +<tt class="descname">TRUST_UNDEFINED</tt><em class="property"> = 0</em><a class="headerlink" href="#gnupg._parsers.Verify.TRUST_UNDEFINED" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Verify.TRUST_NEVER"> +<tt class="descname">TRUST_NEVER</tt><em class="property"> = 1</em><a class="headerlink" href="#gnupg._parsers.Verify.TRUST_NEVER" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Verify.TRUST_MARGINAL"> +<tt class="descname">TRUST_MARGINAL</tt><em class="property"> = 2</em><a class="headerlink" href="#gnupg._parsers.Verify.TRUST_MARGINAL" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Verify.TRUST_FULLY"> +<tt class="descname">TRUST_FULLY</tt><em class="property"> = 3</em><a class="headerlink" href="#gnupg._parsers.Verify.TRUST_FULLY" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Verify.TRUST_ULTIMATE"> +<tt class="descname">TRUST_ULTIMATE</tt><em class="property"> = 4</em><a class="headerlink" href="#gnupg._parsers.Verify.TRUST_ULTIMATE" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Verify.TRUST_LEVELS"> +<tt class="descname">TRUST_LEVELS</tt><em class="property"> = {'TRUST_UNDEFINED': 0, 'TRUST_FULLY': 3, 'TRUST_NEVER': 1, 'TRUST_MARGINAL': 2, 'TRUST_ULTIMATE': 4}</em><a class="headerlink" href="#gnupg._parsers.Verify.TRUST_LEVELS" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Verify.valid"> +<tt class="descname">valid</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Verify.valid" title="Permalink to this definition">¶</a></dt> +<dd><p>True if the signature is valid, False otherwise.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Verify.status"> +<tt class="descname">status</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Verify.status" title="Permalink to this definition">¶</a></dt> +<dd><p>A string describing the status of the signature verification. +Can be one of <tt class="docutils literal"><span class="pre">signature</span> <span class="pre">bad</span></tt>, <tt class="docutils literal"><span class="pre">signature</span> <span class="pre">good</span></tt>, +<tt class="docutils literal"><span class="pre">signature</span> <span class="pre">valid</span></tt>, <tt class="docutils literal"><span class="pre">signature</span> <span class="pre">error</span></tt>, <tt class="docutils literal"><span class="pre">decryption</span> <span class="pre">failed</span></tt>, +<tt class="docutils literal"><span class="pre">no</span> <span class="pre">public</span> <span class="pre">key</span></tt>, <tt class="docutils literal"><span class="pre">key</span> <span class="pre">exp</span></tt>, or <tt class="docutils literal"><span class="pre">key</span> <span class="pre">rev</span></tt>.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Verify.fingerprint"> +<tt class="descname">fingerprint</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Verify.fingerprint" title="Permalink to this definition">¶</a></dt> +<dd><p>The fingerprint of the signing keyid.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Verify.pubkey_fingerprint"> +<tt class="descname">pubkey_fingerprint</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Verify.pubkey_fingerprint" title="Permalink to this definition">¶</a></dt> +<dd><p>The fingerprint of the corresponding public key, which may be +different if the signature was created with a subkey.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Verify.key_id"> +<tt class="descname">key_id</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Verify.key_id" title="Permalink to this definition">¶</a></dt> +<dd><p>The keyid of the signing key.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Verify.signature_id"> +<tt class="descname">signature_id</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Verify.signature_id" title="Permalink to this definition">¶</a></dt> +<dd><p>The id of the signature itself.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Verify.creation_date"> +<tt class="descname">creation_date</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Verify.creation_date" title="Permalink to this definition">¶</a></dt> +<dd><p>The creation date of the signing key.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Verify.timestamp"> +<tt class="descname">timestamp</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Verify.timestamp" title="Permalink to this definition">¶</a></dt> +<dd><p>The timestamp of the purported signature, if we are unable to parse +and/or validate it.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Verify.sig_timestamp"> +<tt class="descname">sig_timestamp</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Verify.sig_timestamp" title="Permalink to this definition">¶</a></dt> +<dd><p>The timestamp for when the valid signature was created.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Verify.username"> +<tt class="descname">username</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Verify.username" title="Permalink to this definition">¶</a></dt> +<dd><p>The userid of the signing key which was used to create the +signature.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Verify.expire_timestamp"> +<tt class="descname">expire_timestamp</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Verify.expire_timestamp" title="Permalink to this definition">¶</a></dt> +<dd><p>When the signing key is due to expire.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Verify.trust_level"> +<tt class="descname">trust_level</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Verify.trust_level" title="Permalink to this definition">¶</a></dt> +<dd><p>An integer 0-4 describing the trust level of the signature.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Verify.trust_text"> +<tt class="descname">trust_text</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Verify.trust_text" title="Permalink to this definition">¶</a></dt> +<dd><p>The string corresponding to the <tt class="docutils literal"><span class="pre">trust_level</span></tt> number.</p> +</dd></dl> + +<dl class="method"> +<dt id="gnupg._parsers.Verify._handle_status"> +<tt class="descname">_handle_status</tt><big>(</big><em>key</em>, <em>value</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#Verify._handle_status"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.Verify._handle_status" title="Permalink to this definition">¶</a></dt> +<dd><p>Parse a status code from the attached GnuPG process.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><a class="reference external" href="http://docs.python.org/library/exceptions.html#exceptions.ValueError" title="(in Python v2.7)"><tt class="xref py py-exc docutils literal"><span class="pre">ValueError</span></tt></a> if the status message is unknown.</td> +</tr> +</tbody> +</table> +</dd></dl> + +</dd></dl> + +<dl class="class"> +<dt id="gnupg._parsers.Crypt"> +<em class="property">class </em><tt class="descname">Crypt</tt><big>(</big><em>gpg</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#Crypt"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.Crypt" title="Permalink to this definition">¶</a></dt> +<dd><p>Bases: <a class="reference internal" href="#gnupg._parsers.Verify" title="gnupg._parsers.Verify"><tt class="xref py py-class docutils literal"><span class="pre">gnupg._parsers.Verify</span></tt></a></p> +<p>Parser for internal status messages from GnuPG for <tt class="docutils literal"><span class="pre">--encrypt</span></tt>, +<tt class="docutils literal"><span class="pre">--decrypt</span></tt>, and <tt class="docutils literal"><span class="pre">--decrypt-files</span></tt>.</p> +<dl class="attribute"> +<dt id="gnupg._parsers.Crypt.data"> +<tt class="descname">data</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Crypt.data" title="Permalink to this definition">¶</a></dt> +<dd><p>A string containing the encrypted or decrypted data.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Crypt.ok"> +<tt class="descname">ok</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Crypt.ok" title="Permalink to this definition">¶</a></dt> +<dd><p>True if the decryption/encryption process turned out okay.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.Crypt.status"> +<tt class="descname">status</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.Crypt.status" title="Permalink to this definition">¶</a></dt> +<dd><p>A string describing the current processing status, or error, if one +has occurred.</p> +</dd></dl> + +<dl class="method"> +<dt id="gnupg._parsers.Crypt._handle_status"> +<tt class="descname">_handle_status</tt><big>(</big><em>key</em>, <em>value</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#Crypt._handle_status"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.Crypt._handle_status" title="Permalink to this definition">¶</a></dt> +<dd><p>Parse a status code from the attached GnuPG process.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><a class="reference external" href="http://docs.python.org/library/exceptions.html#exceptions.ValueError" title="(in Python v2.7)"><tt class="xref py py-exc docutils literal"><span class="pre">ValueError</span></tt></a> if the status message is unknown.</td> +</tr> +</tbody> +</table> +</dd></dl> + +</dd></dl> + +<dl class="class"> +<dt id="gnupg._parsers.ListPackets"> +<em class="property">class </em><tt class="descname">ListPackets</tt><big>(</big><em>gpg</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#ListPackets"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.ListPackets" title="Permalink to this definition">¶</a></dt> +<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></p> +<p>Handle status messages for –list-packets.</p> +<dl class="attribute"> +<dt id="gnupg._parsers.ListPackets.status"> +<tt class="descname">status</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.ListPackets.status" title="Permalink to this definition">¶</a></dt> +<dd><p>A string describing the current processing status, or error, if one +has occurred.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.ListPackets.need_passphrase"> +<tt class="descname">need_passphrase</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.ListPackets.need_passphrase" title="Permalink to this definition">¶</a></dt> +<dd><p>True if the passphrase to a public/private keypair is required.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.ListPackets.need_passphrase_sym"> +<tt class="descname">need_passphrase_sym</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.ListPackets.need_passphrase_sym" title="Permalink to this definition">¶</a></dt> +<dd><p>True if a passphrase for a symmetric key is required.</p> +</dd></dl> + +<dl class="attribute"> +<dt id="gnupg._parsers.ListPackets.userid_hint"> +<tt class="descname">userid_hint</tt><em class="property"> = None</em><a class="headerlink" href="#gnupg._parsers.ListPackets.userid_hint" title="Permalink to this definition">¶</a></dt> +<dd><p>The keyid and uid which this data is encrypted to.</p> +</dd></dl> + +<dl class="method"> +<dt id="gnupg._parsers.ListPackets._handle_status"> +<tt class="descname">_handle_status</tt><big>(</big><em>key</em>, <em>value</em><big>)</big><a class="reference internal" href="_modules/gnupg/_parsers.html#ListPackets._handle_status"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._parsers.ListPackets._handle_status" title="Permalink to this definition">¶</a></dt> +<dd><p>Parse a status code from the attached GnuPG process.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><a class="reference external" href="http://docs.python.org/library/exceptions.html#exceptions.ValueError" title="(in Python v2.7)"><tt class="xref py py-exc docutils literal"><span class="pre">ValueError</span></tt></a> if the status message is unknown.</td> +</tr> +</tbody> +</table> +</dd></dl> + +</dd></dl> + +</div> +<div class="section" id="util-module"> +<span id="util"></span><h2>util module<a class="headerlink" href="#util-module" title="Permalink to this headline">¶</a></h2> +<p>You shouldn’t really need to mess with this module either, it mostly deals +with low-level IO and file handling operations, de-/en- coding issues, and +setting up basic package facilities such as logging.</p> +<span class="target" id="module-gnupg._util"></span><p>Extra utilities for python-gnupg.</p> +<dl class="function"> +<dt id="gnupg._util.find_encodings"> +<tt class="descname">find_encodings</tt><big>(</big><em>enc=None</em>, <em>system=False</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#find_encodings"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util.find_encodings" title="Permalink to this definition">¶</a></dt> +<dd><p>Find functions for encoding translations for a specific codec.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><strong>enc</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The codec to find translation functions for. It will be +normalized by converting to lowercase, excluding +everything which is not ascii, and hyphens will be +converted to underscores.</li> +<li><strong>system</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#bool" title="(in Python v2.7)"><em>bool</em></a>) – If True, find encodings based on the system’s stdin +encoding, otherwise assume utf-8.</li> +</ul> +</td> +</tr> +<tr class="field-even field"><th class="field-name">Raises:</th><td class="field-body"><p class="first last">:exc:LookupError if the normalized codec, <tt class="docutils literal"><span class="pre">enc</span></tt>, cannot be +found in Python’s encoding translation map.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util.author_info"> +<tt class="descname">author_info</tt><big>(</big><em>name</em>, <em>contact=None</em>, <em>public_key=None</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#author_info"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util.author_info" title="Permalink to this definition">¶</a></dt> +<dd><p>Easy object-oriented representation of contributor info.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>name</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The contributor´s name.</li> +<li><strong>contact</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The contributor´s email address or contact +information, if given.</li> +<li><strong>public_key</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The contributor´s public keyid, if given.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._copy_data"> +<tt class="descname">_copy_data</tt><big>(</big><em>instream</em>, <em>outstream</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_copy_data"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._copy_data" title="Permalink to this definition">¶</a></dt> +<dd><p>Copy data from one stream to another.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>instream</strong> (<a class="reference external" href="http://docs.python.org/library/io.html#io.BytesIO" title="(in Python v2.7)"><tt class="xref py py-class docutils literal"><span class="pre">io.BytesIO</span></tt></a> or <a class="reference external" href="http://docs.python.org/library/io.html#io.StringIO" title="(in Python v2.7)"><tt class="xref py py-class docutils literal"><span class="pre">io.StringIO</span></tt></a> or file) – A byte stream or open file to read from.</li> +<li><strong>outstream</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#file" title="(in Python v2.7)"><em>file</em></a>) – The file descriptor of a tmpfile to write to.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._create_if_necessary"> +<tt class="descname">_create_if_necessary</tt><big>(</big><em>directory</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_create_if_necessary"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._create_if_necessary" title="Permalink to this definition">¶</a></dt> +<dd><p>Create the specified directory, if necessary.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>directory</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The directory to use.</td> +</tr> +<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body">bool</td> +</tr> +<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">True if no errors occurred and the directory was created or +existed beforehand, False otherwise.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util.create_uid_email"> +<tt class="descname">create_uid_email</tt><big>(</big><em>username=None</em>, <em>hostname=None</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#create_uid_email"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util.create_uid_email" title="Permalink to this definition">¶</a></dt> +<dd><p>Create an email address suitable for a UID on a GnuPG key.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><strong>username</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The username portion of an email address. If None, +defaults to the username of the running Python +process.</li> +<li><strong>hostname</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The FQDN portion of an email address. If None, the +hostname is obtained from gethostname(2).</li> +</ul> +</td> +</tr> +<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body"><p class="first">str</p> +</td> +</tr> +<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">A string formatted as <username>@<hostname>.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._deprefix"> +<tt class="descname">_deprefix</tt><big>(</big><em>line</em>, <em>prefix</em>, <em>callback=None</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_deprefix"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._deprefix" title="Permalink to this definition">¶</a></dt> +<dd><p>Remove the prefix string from the beginning of line, if it exists.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><strong>line</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#module-string" title="(in Python v2.7)"><em>string</em></a>) – A line, such as one output by GnuPG’s status-fd.</li> +<li><strong>prefix</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#module-string" title="(in Python v2.7)"><em>string</em></a>) – A substring to remove from the beginning of +<tt class="docutils literal"><span class="pre">line</span></tt>. Case insensitive.</li> +<li><strong>callback</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#callable" title="(in Python v2.7)"><em>callable</em></a>) – Function to call if the prefix is found. The signature to +callback will be only one argument, the <tt class="docutils literal"><span class="pre">line</span></tt> without the <tt class="docutils literal"><span class="pre">prefix</span></tt>, i.e. +<tt class="docutils literal"><span class="pre">callback(line)</span></tt>.</li> +</ul> +</td> +</tr> +<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body"><p class="first">string</p> +</td> +</tr> +<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">If the prefix was found, the <tt class="docutils literal"><span class="pre">line</span></tt> without the prefix is +returned. Otherwise, the original <tt class="docutils literal"><span class="pre">line</span></tt> is returned.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._find_binary"> +<tt class="descname">_find_binary</tt><big>(</big><em>binary=None</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_find_binary"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._find_binary" title="Permalink to this definition">¶</a></dt> +<dd><p>Find the absolute path to the GnuPG binary.</p> +<p>Also run checks that the binary is not a symlink, and check that +our process real uid has exec permissions.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>binary</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The path to the GnuPG binary.</td> +</tr> +<tr class="field-even field"><th class="field-name">Raises:</th><td class="field-body"><a class="reference external" href="http://docs.python.org/library/exceptions.html#exceptions.RuntimeError" title="(in Python v2.7)"><tt class="xref py py-exc docutils literal"><span class="pre">RuntimeError</span></tt></a> if it appears that GnuPG is not +installed.</td> +</tr> +<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body">str</td> +</tr> +<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">The absolute path to the GnuPG binary to use, if no exceptions +occur.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._has_readwrite"> +<tt class="descname">_has_readwrite</tt><big>(</big><em>path</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_has_readwrite"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._has_readwrite" title="Permalink to this definition">¶</a></dt> +<dd><p>Determine if the real uid/gid of the executing user has read and write +permissions for a directory or a file.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>path</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The path to the directory or file to check permissions +for.</td> +</tr> +<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body">bool</td> +</tr> +<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">True if real uid/gid has read+write permissions, False otherwise.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._is_file"> +<tt class="descname">_is_file</tt><big>(</big><em>filename</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_is_file"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._is_file" title="Permalink to this definition">¶</a></dt> +<dd><p>Check that the size of the thing which is supposed to be a filename has +size greater than zero, without following symbolic links or using +:func:os.path.isfile.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>filename</strong> – An object to check.</td> +</tr> +<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body">bool</td> +</tr> +<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">True if <strong>filename</strong> is file-like, False otherwise.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._is_stream"> +<tt class="descname">_is_stream</tt><big>(</big><em>input</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_is_stream"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._is_stream" title="Permalink to this definition">¶</a></dt> +<dd><p>Check that the input is a byte stream.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>input</strong> – An object provided for reading from or writing to.</td> +</tr> +<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body">bool</td> +</tr> +<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">True if :param:input is a stream, False if otherwise.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._is_list_or_tuple"> +<tt class="descname">_is_list_or_tuple</tt><big>(</big><em>instance</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_is_list_or_tuple"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._is_list_or_tuple" title="Permalink to this definition">¶</a></dt> +<dd><p>Check that <tt class="docutils literal"><span class="pre">instance</span></tt> is a list or tuple.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>instance</strong> – The object to type check.</td> +</tr> +<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body">bool</td> +</tr> +<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">True if <tt class="docutils literal"><span class="pre">instance</span></tt> is a list or tuple, False otherwise.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._is_gpg1"> +<tt class="descname">_is_gpg1</tt><big>(</big><em>version</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_is_gpg1"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._is_gpg1" title="Permalink to this definition">¶</a></dt> +<dd><p>Returns True if using GnuPG version 1.x.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>version</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#tuple" title="(in Python v2.7)"><em>tuple</em></a>) – A tuple of three integers indication major, minor, +and micro version numbers.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._is_gpg2"> +<tt class="descname">_is_gpg2</tt><big>(</big><em>version</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_is_gpg2"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._is_gpg2" title="Permalink to this definition">¶</a></dt> +<dd><p>Returns True if using GnuPG version 2.x.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>version</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#tuple" title="(in Python v2.7)"><em>tuple</em></a>) – A tuple of three integers indication major, minor, +and micro version numbers.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._make_binary_stream"> +<tt class="descname">_make_binary_stream</tt><big>(</big><em>s</em>, <em>encoding</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_make_binary_stream"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._make_binary_stream" title="Permalink to this definition">¶</a></dt> +<dd><p>xxx fill me in</p> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._make_passphrase"> +<tt class="descname">_make_passphrase</tt><big>(</big><em>length=None</em>, <em>save=False</em>, <em>file=None</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_make_passphrase"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._make_passphrase" title="Permalink to this definition">¶</a></dt> +<dd><p>Create a passphrase and write it to a file that only the user can read.</p> +<p>This is not very secure, and should not be relied upon for actual key +passphrases.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>length</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#int" title="(in Python v2.7)"><em>int</em></a>) – The length in bytes of the string to generate.</li> +<li><strong>file</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#file" title="(in Python v2.7)"><em>file</em></a>) – The file to save the generated passphrase in. If not +given, defaults to ‘passphrase-<the real user id>-<seconds since +epoch>’ in the top-level directory.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._make_random_string"> +<tt class="descname">_make_random_string</tt><big>(</big><em>length</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_make_random_string"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._make_random_string" title="Permalink to this definition">¶</a></dt> +<dd><p>Returns a random lowercase, uppercase, alphanumerical string.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>length</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#int" title="(in Python v2.7)"><em>int</em></a>) – The length in bytes of the string to generate.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._match_version_string"> +<tt class="descname">_match_version_string</tt><big>(</big><em>version</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_match_version_string"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._match_version_string" title="Permalink to this definition">¶</a></dt> +<dd><p>Sort a binary version string into major, minor, and micro integers.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>version</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – A version string in the form x.x.x</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._next_year"> +<tt class="descname">_next_year</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_next_year"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._next_year" title="Permalink to this definition">¶</a></dt> +<dd><p>Get the date of today plus one year.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body">str</td> +</tr> +<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">The date of this day next year, in the format ‘%Y-%m-%d’.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._now"> +<tt class="descname">_now</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_now"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._now" title="Permalink to this definition">¶</a></dt> +<dd><p>Get a timestamp for right now, formatted according to ISO 8601.</p> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._separate_keyword"> +<tt class="descname">_separate_keyword</tt><big>(</big><em>line</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_separate_keyword"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._separate_keyword" title="Permalink to this definition">¶</a></dt> +<dd><p>Split the line, and return (first_word, the_rest).</p> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._threaded_copy_data"> +<tt class="descname">_threaded_copy_data</tt><big>(</big><em>instream</em>, <em>outstream</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_threaded_copy_data"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._threaded_copy_data" title="Permalink to this definition">¶</a></dt> +<dd><p>Copy data from one stream to another in a separate thread.</p> +<p>Wraps <tt class="docutils literal"><span class="pre">_copy_data()</span></tt> in a <a class="reference external" href="http://docs.python.org/library/threading.html#threading.Thread" title="(in Python v2.7)"><tt class="xref py py-class docutils literal"><span class="pre">threading.Thread</span></tt></a>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>instream</strong> (<a class="reference external" href="http://docs.python.org/library/io.html#io.BytesIO" title="(in Python v2.7)"><tt class="xref py py-class docutils literal"><span class="pre">io.BytesIO</span></tt></a> or <a class="reference external" href="http://docs.python.org/library/io.html#io.StringIO" title="(in Python v2.7)"><tt class="xref py py-class docutils literal"><span class="pre">io.StringIO</span></tt></a>) – A byte stream to read from.</li> +<li><strong>outstream</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#file" title="(in Python v2.7)"><em>file</em></a>) – The file descriptor of a tmpfile to write to.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._utc_epoch"> +<tt class="descname">_utc_epoch</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_utc_epoch"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._utc_epoch" title="Permalink to this definition">¶</a></dt> +<dd><p>Get the seconds since epoch.</p> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._which"> +<tt class="descname">_which</tt><big>(</big><em>executable</em>, <em>flags=1</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_which"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._which" title="Permalink to this definition">¶</a></dt> +<dd><p>Borrowed from Twisted’s :mod:twisted.python.proutils .</p> +<p>Search PATH for executable files with the given name.</p> +<p>On newer versions of MS-Windows, the PATHEXT environment variable will be +set to the list of file extensions for files considered executable. This +will normally include things like ”.EXE”. This fuction will also find files +with the given name ending with any of these extensions.</p> +<p>On MS-Windows the only flag that has any meaning is os.F_OK. Any other +flags will be ignored.</p> +<p>Note: This function does not help us prevent an attacker who can already +manipulate the environment’s PATH settings from placing malicious code +higher in the PATH. It also does happily follows links.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><strong>name</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The name for which to search.</li> +<li><strong>flags</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#int" title="(in Python v2.7)"><em>int</em></a>) – Arguments to L{os.access}.</li> +</ul> +</td> +</tr> +<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body"><p class="first">list</p> +</td> +</tr> +<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">A list of the full paths to files found, in the order in which +they were found.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="gnupg._util._write_passphrase"> +<tt class="descname">_write_passphrase</tt><big>(</big><em>stream</em>, <em>passphrase</em>, <em>encoding</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#_write_passphrase"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util._write_passphrase" title="Permalink to this definition">¶</a></dt> +<dd><p>Write the passphrase from memory to the GnuPG process’ stdin.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><strong>stream</strong> (file, <a class="reference external" href="http://docs.python.org/library/io.html#io.BytesIO" title="(in Python v2.7)"><tt class="xref py py-class docutils literal"><span class="pre">BytesIO</span></tt></a>, or <a class="reference external" href="http://docs.python.org/library/io.html#io.StringIO" title="(in Python v2.7)"><tt class="xref py py-class docutils literal"><span class="pre">StringIO</span></tt></a>) – The input file descriptor to write the password to.</li> +<li><strong>passphrase</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The passphrase for the secret key material.</li> +<li><strong>encoding</strong> (<a class="reference external" href="http://docs.python.org/library/functions.html#str" title="(in Python v2.7)"><em>str</em></a>) – The data encoding expected by GnuPG. Usually, this +is <tt class="docutils literal"><span class="pre">sys.getfilesystemencoding()</span></tt>.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="class"> +<dt id="gnupg._util.InheritableProperty"> +<em class="property">class </em><tt class="descname">InheritableProperty</tt><big>(</big><em>fget=None</em>, <em>fset=None</em>, <em>fdel=None</em>, <em>doc=None</em><big>)</big><a class="reference internal" href="_modules/gnupg/_util.html#InheritableProperty"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util.InheritableProperty" title="Permalink to this definition">¶</a></dt> +<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></p> +<p>Based on the emulation of PyProperty_Type() in Objects/descrobject.c</p> +</dd></dl> + +<dl class="class"> +<dt id="gnupg._util.Storage"> +<em class="property">class </em><tt class="descname">Storage</tt><a class="reference internal" href="_modules/gnupg/_util.html#Storage"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#gnupg._util.Storage" title="Permalink to this definition">¶</a></dt> +<dd><p>Bases: <a class="reference external" href="http://docs.python.org/library/stdtypes.html#dict" title="(in Python v2.7)"><tt class="xref py py-class docutils literal"><span class="pre">dict</span></tt></a></p> +<p>A dictionary where keys are stored as class attributes.</p> +<p>For example, <tt class="docutils literal"><span class="pre">obj.foo</span></tt> can be used in addition to <tt class="docutils literal"><span class="pre">obj['foo']</span></tt>:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">o</span> <span class="o">=</span> <span class="n">Storage</span><span class="p">(</span><span class="n">a</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span> +<span class="gp">>>> </span><span class="n">o</span><span class="o">.</span><span class="n">a</span> +<span class="go">1</span> +<span class="gp">>>> </span><span class="n">o</span><span class="p">[</span><span class="s">'a'</span><span class="p">]</span> +<span class="go">1</span> +<span class="gp">>>> </span><span class="n">o</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="mi">2</span> +<span class="gp">>>> </span><span class="n">o</span><span class="p">[</span><span class="s">'a'</span><span class="p">]</span> +<span class="go">2</span> +<span class="gp">>>> </span><span class="k">del</span> <span class="n">o</span><span class="o">.</span><span class="n">a</span> +<span class="gp">>>> </span><span class="n">o</span><span class="o">.</span><span class="n">a</span> +<span class="go">None</span> +</pre></div> +</div> +</dd></dl> + +</div> +<div class="section" id="about-this-fork"> +<h2>About this fork<a class="headerlink" href="#about-this-fork" title="Permalink to this headline">¶</a></h2> +<p>This is a modified version of <a class="reference external" href="https://code.google.com/p/python-gnupg/">python-gnupg</a>, (forked from version 0.3.2) which +was created by Vinay Sajip, which itself is a modification of GPG.py written +by Steve Traugott, which in turn is a modification of the pycrypto GnuPG +interface written by A.M. Kuchling.</p> +<p>This version is patched to sanitize untrusted inputs, due to the necessity of +executing <tt class="docutils literal"><span class="pre">subprocess.Popen([...],</span> <span class="pre">shell=True)</span></tt> in order to communicate with +GnuPG. Several speed improvements were also made based on code profiling, and +the API has been cleaned up to support an easier, more Pythonic, interaction.</p> +</div> +<div class="section" id="previous-authors-documentation"> +<h2>Previous Authors’ Documentation<a class="headerlink" href="#previous-authors-documentation" title="Permalink to this headline">¶</a></h2> +<dl class="docutils"> +<dt>Steve Traugott’s documentation:</dt> +<dd><div class="first last line-block"> +<div class="line"><br /></div> +<div class="line-block"> +<div class="line">Portions of this module are derived from A.M. Kuchling’s well-designed</div> +<div class="line">GPG.py, using Richard Jones’ updated version 1.3, which can be found in</div> +<div class="line">the pycrypto CVS repository on Sourceforge:</div> +<div class="line"><br /></div> +<div class="line"><a class="reference external" href="http://pycrypto.cvs.sourceforge.net/viewvc/pycrypto/gpg/GPG.py">http://pycrypto.cvs.sourceforge.net/viewvc/pycrypto/gpg/GPG.py</a></div> +<div class="line"><br /></div> +<div class="line">This module is <em>not</em> forward-compatible with amk’s; some of the old</div> +<div class="line">interface has changed. For instance, since I’ve added decrypt</div> +<div class="line">functionality, I elected to initialize with a ‘gpghome’ argument instead</div> +<div class="line">of ‘keyring’, so that gpg can find both the public and secret keyrings.</div> +<div class="line">I’ve also altered some of the returned objects in order for the caller to</div> +<div class="line">not have to know as much about the internals of the result classes.</div> +<div class="line"><br /></div> +<div class="line">While the rest of ISconf is released under the GPL, I am releasing this</div> +<div class="line">single file under the same terms that A.M. Kuchling used for pycrypto.</div> +<div class="line"><br /></div> +<div class="line">Steve Traugott, <a class="reference external" href="mailto:stevegt%40terraluna.org">stevegt<span>@</span>terraluna<span>.</span>org</a></div> +<div class="line">Thu Jun 23 21:27:20 PDT 2005</div> +</div> +</div> +</dd> +<dt>Vinay Sajip’s documentation:</dt> +<dd><div class="first last line-block"> +<div class="line"><br /></div> +<div class="line-block"> +<div class="line">This version of the module has been modified from Steve Traugott’s version</div> +<div class="line">(see <a class="reference external" href="http://trac.t7a.org/isconf/browser/trunk/lib/python/isconf/GPG.py">http://trac.t7a.org/isconf/browser/trunk/lib/python/isconf/GPG.py</a>) by</div> +<div class="line">Vinay Sajip to make use of the subprocess module (Steve’s version uses</div> +<div class="line">os.fork() and so does not work on Windows). Renamed to gnupg.py to avoid</div> +<div class="line">confusion with the previous versions.</div> +<div class="line"><br /></div> +<div class="line">A unittest harness (test_gnupg.py) has also been added.</div> +<div class="line"><br /></div> +<div class="line">Modifications Copyright (C) 2008-2012 Vinay Sajip. All rights reserved.</div> +</div> +</div> +</dd> +</dl> +</div> +</div> + + + </div> + </div> + </div> + </div> + <div class="sidebar"> + <h3>Table Of Contents</h3> + <ul class="current"> +<li class="toctree-l1 current"><a class="current reference internal" href="">gnupg package</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#gnupg-module">gnupg module</a></li> +<li class="toctree-l2"><a class="reference internal" href="#meta-module">meta module</a></li> +<li class="toctree-l2"><a class="reference internal" href="#parsers-module">parsers module</a></li> +<li class="toctree-l2"><a class="reference internal" href="#util-module">util module</a></li> +<li class="toctree-l2"><a class="reference internal" href="#about-this-fork">About this fork</a></li> +<li class="toctree-l2"><a class="reference internal" href="#previous-authors-documentation">Previous Authors’ Documentation</a></li> +</ul> +</li> +</ul> + + <h3 style="margin-top: 1.5em;">Search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <div class="clearer"></div> + </div> + </div> + + <div class="footer-wrapper"> + <div class="footer"> + <div class="left"> + <a href="index.html" title="gnupg: Python Package Documentation" + >previous</a> | + <a href="py-modindex.html" title="Python Module Index" + >modules</a> | + <a href="genindex.html" title="General Index" + >index</a> + <br/> + <a href="_sources/gnupg.txt" + rel="nofollow">Show Source</a> + </div> + + <div class="right"> + + <div class="footer"> + © Copyright 2013-2014, Isis Agora Lovecruft. + Last updated on Saturday, 02 August 2014. + Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2. + </div> + </div> + <div class="clearer"></div> + </div> + </div> + + </body> +</html>
\ No newline at end of file |