/usr/share/doc/python3-pgpy/html/examples.html is in python3-pgpy-doc 0.4.3-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 | <!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>Examples — PGPy 0.4.3 documentation</title>
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/progress.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '0.4.3',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</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="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Keys" href="examples/keys.html" />
<link rel="prev" title="Installation" href="installation.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head>
<body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="examples">
<h1>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h1>
<div class="toctree-wrapper compound">
</div>
<div class="section" id="keys">
<h2>Keys<a class="headerlink" href="#keys" title="Permalink to this headline">¶</a></h2>
<div class="section" id="generating-keys">
<h3>Generating Keys<a class="headerlink" href="#generating-keys" title="Permalink to this headline">¶</a></h3>
<p>PGPy can generate most types keys as defined in the standard.</p>
<div class="section" id="generating-primary-keys">
<h4>Generating Primary Keys<a class="headerlink" href="#generating-primary-keys" title="Permalink to this headline">¶</a></h4>
<p>It is possible to generate most types of keys with PGPy now. The process is mostly straightforward:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">pgpy.constants</span> <span class="k">import</span> <span class="n">PubKeyAlgorithm</span><span class="p">,</span> <span class="n">KeyFlags</span><span class="p">,</span> <span class="n">HashAlgorithm</span><span class="p">,</span> <span class="n">SymmetricKeyAlgorithm</span><span class="p">,</span> <span class="n">CompressionAlgorithm</span>
<span class="c1"># we can start by generating a primary key. For this example, we'll use RSA, but it could be DSA or ECDSA as well</span>
<span class="n">key</span> <span class="o">=</span> <span class="n">pgpy</span><span class="o">.</span><span class="n">PGPKey</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="n">PubKeyAlgorithm</span><span class="o">.</span><span class="n">RSAEncryptOrSign</span><span class="p">,</span> <span class="mi">4096</span><span class="p">)</span>
<span class="c1"># we now have some key material, but our new key doesn't have a user ID yet, and therefore is not yet usable!</span>
<span class="n">uid</span> <span class="o">=</span> <span class="n">pgpy</span><span class="o">.</span><span class="n">PGPUID</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="s1">'Abraham Lincoln'</span><span class="p">,</span> <span class="n">comment</span><span class="o">=</span><span class="s1">'Honest Abe'</span><span class="p">,</span> <span class="n">email</span><span class="o">=</span><span class="s1">'abraham.lincoln@whitehouse.gov'</span><span class="p">)</span>
<span class="c1"># now we must add the new user id to the key. We'll need to specify all of our preferences at this point</span>
<span class="c1"># because PGPy doesn't have any built-in key preference defaults at this time</span>
<span class="c1"># this example is similar to GnuPG 2.1.x defaults, with no expiration or preferred keyserver</span>
<span class="n">key</span><span class="o">.</span><span class="n">add_uid</span><span class="p">(</span><span class="n">uid</span><span class="p">,</span> <span class="n">usage</span><span class="o">=</span><span class="p">{</span><span class="n">KeyFlags</span><span class="o">.</span><span class="n">Sign</span><span class="p">,</span> <span class="n">KeyFlags</span><span class="o">.</span><span class="n">EncryptCommunications</span><span class="p">,</span> <span class="n">KeyFlags</span><span class="o">.</span><span class="n">EncryptStorage</span><span class="p">},</span>
<span class="n">hashes</span><span class="o">=</span><span class="p">[</span><span class="n">HashAlgorithm</span><span class="o">.</span><span class="n">SHA256</span><span class="p">,</span> <span class="n">HashAlgorithm</span><span class="o">.</span><span class="n">SHA384</span><span class="p">,</span> <span class="n">HashAlgorithm</span><span class="o">.</span><span class="n">SHA512</span><span class="p">,</span> <span class="n">HashAlgorithm</span><span class="o">.</span><span class="n">SHA224</span><span class="p">],</span>
<span class="n">ciphers</span><span class="o">=</span><span class="p">[</span><span class="n">SymmetricKeyAlgorithm</span><span class="o">.</span><span class="n">AES256</span><span class="p">,</span> <span class="n">SymmetricKeyAlgorithm</span><span class="o">.</span><span class="n">AES192</span><span class="p">,</span> <span class="n">SymmetricKeyAlgorithm</span><span class="o">.</span><span class="n">AES128</span><span class="p">],</span>
<span class="n">compression</span><span class="o">=</span><span class="p">[</span><span class="n">CompressionAlgorithm</span><span class="o">.</span><span class="n">ZLIB</span><span class="p">,</span> <span class="n">CompressionAlgorithm</span><span class="o">.</span><span class="n">BZ2</span><span class="p">,</span> <span class="n">CompressionAlgorithm</span><span class="o">.</span><span class="n">ZIP</span><span class="p">,</span> <span class="n">CompressionAlgorithm</span><span class="o">.</span><span class="n">Uncompressed</span><span class="p">])</span>
</pre></div>
</div>
<p>Specifying key expiration can be done using the <code class="docutils literal"><span class="pre">key_expires</span></code> keyword when adding the user id. Expiration can be specified
using a <code class="xref py py-obj docutils literal"><span class="pre">datetime.datetime</span></code> or a <code class="xref py py-obj docutils literal"><span class="pre">datetime.timedelta</span></code> object:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">datetime</span> <span class="k">import</span> <span class="n">timedelta</span>
<span class="c1"># in this example, we'll use fewer preferences for the sake of brevity, and set the key to expire in 10 years</span>
<span class="n">key</span> <span class="o">=</span> <span class="n">pgpy</span><span class="o">.</span><span class="n">PGPKey</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="n">PubKeyAlgorithm</span><span class="o">.</span><span class="n">RSAEncryptOrSign</span><span class="p">,</span> <span class="mi">4096</span><span class="p">)</span>
<span class="n">uid</span> <span class="o">=</span> <span class="n">pgpy</span><span class="o">.</span><span class="n">PGPUID</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="s1">'Nikola Tesla'</span><span class="p">)</span> <span class="c1"># comment and email are optional</span>
<span class="c1"># the key_expires keyword accepts a :py:obj:`datetime.datetime`</span>
<span class="n">key</span><span class="o">.</span><span class="n">add_uid</span><span class="p">(</span><span class="n">uid</span><span class="p">,</span> <span class="n">usage</span><span class="o">=</span><span class="p">{</span><span class="n">KeyFlags</span><span class="o">.</span><span class="n">Sign</span><span class="p">},</span> <span class="n">hashes</span><span class="o">=</span><span class="p">[</span><span class="n">HashAlgorithm</span><span class="o">.</span><span class="n">SHA512</span><span class="p">,</span> <span class="n">HashAlgorithm</span><span class="o">.</span><span class="n">SHA256</span><span class="p">],</span>
<span class="n">ciphers</span><span class="o">=</span><span class="p">[</span><span class="n">SymmetricKeyAlgorithm</span><span class="o">.</span><span class="n">AES256</span><span class="p">,</span> <span class="n">SymmetricKeyAlgorithm</span><span class="o">.</span><span class="n">Camellia256</span><span class="p">],</span>
<span class="n">compression</span><span class="o">=</span><span class="p">[</span><span class="n">CompressionAlgorithm</span><span class="o">.</span><span class="n">BZ2</span><span class="p">,</span> <span class="n">CompressionAlgorithm</span><span class="o">.</span><span class="n">Uncompressed</span><span class="p">],</span>
<span class="n">key_expires</span><span class="o">=</span><span class="n">timedelta</span><span class="p">(</span><span class="n">days</span><span class="o">=</span><span class="mi">365</span><span class="p">))</span>
</pre></div>
</div>
</div>
<div class="section" id="generating-sub-keys">
<h4>Generating Sub Keys<a class="headerlink" href="#generating-sub-keys" title="Permalink to this headline">¶</a></h4>
<p>Generating a subkey is similar to the process above, except that it requires an existing primary key:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># assuming we already have a primary key, we can generate a new key and add it as a subkey thusly:</span>
<span class="n">subkey</span> <span class="o">=</span> <span class="n">pgpy</span><span class="o">.</span><span class="n">PGPKey</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="n">PubKeyAlgorithm</span><span class="o">.</span><span class="n">RSA</span><span class="p">,</span> <span class="mi">4096</span><span class="p">)</span>
<span class="c1"># preferences that are specific to the subkey can be chosen here</span>
<span class="c1"># any preference(s) needed for actions by this subkey that not specified here</span>
<span class="c1"># will seamlessly "inherit" from those specified on the selected User ID</span>
<span class="n">key</span><span class="o">.</span><span class="n">add_subkey</span><span class="p">(</span><span class="n">subkey</span><span class="p">,</span> <span class="n">usage</span><span class="o">=</span><span class="p">{</span><span class="n">KeyFlags</span><span class="o">.</span><span class="n">Authentication</span><span class="p">})</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="loading-keys">
<h3>Loading Keys<a class="headerlink" href="#loading-keys" title="Permalink to this headline">¶</a></h3>
<p>There are two ways to load keys: individually, or in a keyring.</p>
<div class="section" id="loading-keys-individually">
<h4>Loading Keys Individually<a class="headerlink" href="#loading-keys-individually" title="Permalink to this headline">¶</a></h4>
<p>Keys can be loaded individually into PGPKey objects:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># A new, empty PGPkey object can be instantiated, but this is not very useful</span>
<span class="c1"># by itself.</span>
<span class="c1"># ASCII or binary data can be parsed into an empty PGPKey object with the .parse()</span>
<span class="c1"># method</span>
<span class="n">empty_key</span> <span class="o">=</span> <span class="n">pgpy</span><span class="o">.</span><span class="n">PGPKey</span><span class="p">()</span>
<span class="n">empty_key</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="n">keyblob</span><span class="p">)</span>
<span class="c1"># A key can be loaded from a file, like so:</span>
<span class="n">key</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="n">pgpy</span><span class="o">.</span><span class="n">PGPKey</span><span class="o">.</span><span class="n">from_file</span><span class="p">(</span><span class="s1">'path/to/key.asc'</span><span class="p">)</span>
<span class="c1"># or from a text or binary string/bytes/bytearray that has already been read in:</span>
<span class="n">key</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="n">pgpy</span><span class="o">.</span><span class="n">PGPKey</span><span class="o">.</span><span class="n">from_blob</span><span class="p">(</span><span class="n">keyblob</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="loading-keys-into-a-keyring">
<h4>Loading Keys Into a Keyring<a class="headerlink" href="#loading-keys-into-a-keyring" title="Permalink to this headline">¶</a></h4>
<p>If you intend to maintain multiple keys in memory for extended periods, using a PGPKeyring may be more appropriate:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># These two methods are mostly equivalent</span>
<span class="n">kr</span> <span class="o">=</span> <span class="n">pgpy</span><span class="o">.</span><span class="n">PGPKeyring</span><span class="p">(</span><span class="n">glob</span><span class="o">.</span><span class="n">glob</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">expanduser</span><span class="p">(</span><span class="s1">'~/.gnupg/*ring.gpg'</span><span class="p">)))</span>
<span class="c1"># the only advantage to doing it this way, is the .load method returns a set containing</span>
<span class="c1"># the fingerprints of all keys and subkeys that were loaded this time</span>
<span class="n">kr</span> <span class="o">=</span> <span class="n">pgpy</span><span class="o">.</span><span class="n">PGPKeyring</span><span class="p">()</span>
<span class="n">loaded</span> <span class="o">=</span> <span class="n">kr</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="n">glob</span><span class="o">.</span><span class="n">glob</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">expanduser</span><span class="p">(</span><span class="s1">'~/.gnupg/*ring.gpg'</span><span class="p">)))</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="key-operations">
<h3>Key Operations<a class="headerlink" href="#key-operations" title="Permalink to this headline">¶</a></h3>
<p>Once you have one or more keys generated or loaded, there are some things you may need or want to do before they can be used.</p>
<div class="section" id="passphrase-protecting-secret-keys">
<h4>Passphrase Protecting Secret Keys<a class="headerlink" href="#passphrase-protecting-secret-keys" title="Permalink to this headline">¶</a></h4>
<p>It is usually recommended to passphrase-protect private keys. Adding a passphrase to a key is simple:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># key.is_public is False</span>
<span class="c1"># key.is_protected is False</span>
<span class="n">key</span><span class="o">.</span><span class="n">protect</span><span class="p">(</span><span class="s2">"C0rrectPassphr@se"</span><span class="p">,</span> <span class="n">SymmetricKeyAlgorithm</span><span class="o">.</span><span class="n">AES256</span><span class="p">,</span> <span class="n">HashAlgorithm</span><span class="o">.</span><span class="n">SHA256</span><span class="p">)</span>
<span class="c1"># key.is_protected is now True</span>
</pre></div>
</div>
</div>
<div class="section" id="unlocking-protected-secret-keys">
<h4>Unlocking Protected Secret Keys<a class="headerlink" href="#unlocking-protected-secret-keys" title="Permalink to this headline">¶</a></h4>
<p>If you have a key that is protected with a passphrase, you will need to unlock it first. PGPy handles this using
a context manager block, which also removes the unprotected key material from the object once execution exits that block.</p>
<p>Key unlocking is quite simple:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># enc_key.is_public is False</span>
<span class="c1"># enc_key.is_protected is True</span>
<span class="c1"># enc_key.is_unlocked is False</span>
<span class="c1"># Note that this context manager yields self, so while you can supply `as cvar`, it isn't strictly required</span>
<span class="c1"># If the passphrase given is incorrect, this will raise PGPDecryptionError</span>
<span class="k">with</span> <span class="n">enc_key</span><span class="o">.</span><span class="n">unlock</span><span class="p">(</span><span class="s2">"C0rrectPassphr@se"</span><span class="p">):</span>
<span class="c1"># enc_key.is_unlocked is now True</span>
<span class="o">...</span>
<span class="c1"># This form works equivalently, but may be more semantically clear in some cases:</span>
<span class="k">with</span> <span class="n">enc_key</span><span class="o">.</span><span class="n">unlock</span><span class="p">(</span><span class="s2">"C0rrectPassphr@se"</span><span class="p">)</span> <span class="k">as</span> <span class="n">ukey</span><span class="p">:</span>
<span class="c1"># ukey is just a reference to enc_key in this case</span>
<span class="o">...</span>
</pre></div>
</div>
</div>
<div class="section" id="exporting-keys">
<h4>Exporting Keys<a class="headerlink" href="#exporting-keys" title="Permalink to this headline">¶</a></h4>
<p>Keys can be exported in OpenPGP compliant binary or ASCII-armored formats.</p>
<p>In Python 3:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># binary</span>
<span class="n">keybytes</span> <span class="o">=</span> <span class="nb">bytes</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
<span class="c1"># ASCII armored</span>
<span class="n">keystr</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
</pre></div>
</div>
<p>in Python 2:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># binary</span>
<span class="n">keybytes</span> <span class="o">=</span> <span class="n">key</span><span class="o">.</span><span class="fm">__bytes__</span><span class="p">()</span>
<span class="c1"># ASCII armored</span>
<span class="n">keystr</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
</div>
<div class="section" id="messages">
<h2>Messages<a class="headerlink" href="#messages" title="Permalink to this headline">¶</a></h2>
<p>Other than plaintext, you may want to be able to form PGP Messages. These can be signed and then encrypted to one or
more recipients.</p>
<div class="section" id="creating-new-messages">
<h3>Creating New Messages<a class="headerlink" href="#creating-new-messages" title="Permalink to this headline">¶</a></h3>
<p>New messages can be created quite easily:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># this creates a standard message from text</span>
<span class="c1"># it will also be compressed, by default with ZIP DEFLATE, unless otherwise specified</span>
<span class="n">text_message</span> <span class="o">=</span> <span class="n">pgpy</span><span class="o">.</span><span class="n">PGPMessage</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="s2">"This is a brand spankin' new message!"</span><span class="p">)</span>
<span class="c1"># if you'd like to pack a file into a message instead, you can do so</span>
<span class="c1"># PGPMessage will store the basename of the file and the time it was last modified.</span>
<span class="n">file_message</span> <span class="o">=</span> <span class="n">pgpy</span><span class="o">.</span><span class="n">PGPMessage</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="s2">"path/to/a/file"</span><span class="p">,</span> <span class="n">file</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="c1"># or, if you want to create a *cleartext* message, which is what you may know as a</span>
<span class="c1"># canonicalized text document with an inline signature block, that is done by setting</span>
<span class="c1"># cleartext=True. You can load the contents of a file as above, as well.</span>
<span class="n">ct_message</span> <span class="o">=</span> <span class="n">pgpy</span><span class="o">.</span><span class="n">PGPMessage</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="s2">"This is a shiny new cleartext document. Hooray!"</span><span class="p">,</span>
<span class="n">cleartext</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="loading-existing-messages">
<h3>Loading Existing Messages<a class="headerlink" href="#loading-existing-messages" title="Permalink to this headline">¶</a></h3>
<p>Existing messages can also be loaded very simply. This is nearly identical to loading keys, except that
it only returns the new message object, instead of a tuple:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># PGPMessage will automatically determine if this is a cleartext message or not</span>
<span class="n">message_from_file</span> <span class="o">=</span> <span class="n">pgpy</span><span class="o">.</span><span class="n">PGPMessage</span><span class="o">.</span><span class="n">from_file</span><span class="p">(</span><span class="s2">"path/to/a/message"</span><span class="p">)</span>
<span class="n">message_from_blob</span> <span class="o">=</span> <span class="n">pgpy</span><span class="o">.</span><span class="n">PGPMessage</span><span class="o">.</span><span class="n">from_blob</span><span class="p">(</span><span class="n">msg_blob</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="exporting-messages">
<h3>Exporting Messages<a class="headerlink" href="#exporting-messages" title="Permalink to this headline">¶</a></h3>
<p>Messages can be exported in OpenPGP compliant binary or ASCII-armored formats.</p>
<p>In Python 3:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># binary</span>
<span class="n">msgbytes</span> <span class="o">=</span> <span class="nb">bytes</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>
<span class="c1"># ASCII armored</span>
<span class="c1"># if message is cleartext, this will also properly canonicalize and dash-escape</span>
<span class="c1"># the message text</span>
<span class="n">msgstr</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>
</pre></div>
</div>
<p>in Python 2:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># binary</span>
<span class="n">msgbytes</span> <span class="o">=</span> <span class="n">message</span><span class="o">.</span><span class="fm">__bytes__</span><span class="p">()</span>
<span class="c1"># ASCII armored</span>
<span class="c1"># if message is cleartext, this will also properly canonicalize and dash-escape</span>
<span class="c1"># the message text</span>
<span class="n">msgstr</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="actions">
<h2>Actions<a class="headerlink" href="#actions" title="Permalink to this headline">¶</a></h2>
<div class="section" id="signing-things">
<h3>Signing Things<a class="headerlink" href="#signing-things" title="Permalink to this headline">¶</a></h3>
<p>One of the things you may want to do with PGPKeys is to sign things. This is split into several categories in order
to keep the method signatures relatively simple. Remember that signing requires a private key.</p>
<div class="section" id="text-messages-other">
<h4>Text/Messages/Other<a class="headerlink" href="#text-messages-other" title="Permalink to this headline">¶</a></h4>
<p>Text and messages can be signed using the .sign method:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># sign some text</span>
<span class="n">sig</span> <span class="o">=</span> <span class="n">sec</span><span class="o">.</span><span class="n">sign</span><span class="p">(</span><span class="s2">"I have just signed this text!"</span><span class="p">)</span>
<span class="c1"># sign a message</span>
<span class="c1"># the bitwise OR operator '|' is used to add a signature to a PGPMessage.</span>
<span class="n">message</span> <span class="o">|=</span> <span class="n">sec</span><span class="o">.</span><span class="n">sign</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>
<span class="c1"># timestamp signatures can also be generated, like so.</span>
<span class="c1"># Note that GnuPG seems to have no idea what to do with this</span>
<span class="n">timesig</span> <span class="o">=</span> <span class="n">sec</span><span class="o">.</span><span class="n">sign</span><span class="p">(</span><span class="kc">None</span><span class="p">)</span>
<span class="c1"># if optional parameters are supplied, then a standalone signature is created</span>
<span class="c1"># instead of a timestamp signature. Effectively, they are equivalent, except</span>
<span class="c1"># that the standalone signature has more information in it.</span>
<span class="n">lone_sig</span> <span class="o">=</span> <span class="n">sec</span><span class="o">.</span><span class="n">sign</span><span class="p">(</span><span class="kc">None</span><span class="p">,</span> <span class="n">notation</span><span class="o">=</span><span class="p">{</span><span class="s2">"cheese status"</span><span class="p">:</span> <span class="s2">"standing alone"</span><span class="p">})</span>
</pre></div>
</div>
</div>
<div class="section" id="keys-user-ids">
<h4>Keys/User IDs<a class="headerlink" href="#keys-user-ids" title="Permalink to this headline">¶</a></h4>
<p>Keys and User IDs can be signed using the .certify method:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Sign a key - this creates a Signature Directly On A Key.</span>
<span class="c1"># GnuPG only partially supports this type of signature.</span>
<span class="n">someones_pubkey</span> <span class="o">|=</span> <span class="n">mykey</span><span class="o">.</span><span class="n">certify</span><span class="p">(</span><span class="n">someones_pubkey</span><span class="p">)</span>
<span class="c1"># Sign the primary User ID - this creates the usual certification signature</span>
<span class="c1"># that is best supported by other popular OpenPGP implementations.</span>
<span class="c1"># As above, the bitwise OR operator '|' is used to add a signature to a PGPUID.</span>
<span class="n">cert</span> <span class="o">=</span> <span class="n">mykey</span><span class="o">.</span><span class="n">certify</span><span class="p">(</span><span class="n">someones_pubkey</span><span class="o">.</span><span class="n">userids</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">level</span><span class="o">=</span><span class="n">SignatureType</span><span class="o">.</span><span class="n">Persona_Cert</span><span class="p">)</span>
<span class="n">someones_pubkey</span><span class="o">.</span><span class="n">userids</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">|=</span> <span class="n">cert</span>
<span class="c1"># If you want to sign all of their User IDs, that can be done easily in a loop.</span>
<span class="c1"># This is equivalent to GnuPG's default behavior when signing someone's public key.</span>
<span class="c1"># As above, the bitwise OR operator '|' is used to add a signature to a PGPKey.</span>
<span class="k">for</span> <span class="n">uid</span> <span class="ow">in</span> <span class="n">someones_pubkey</span><span class="o">.</span><span class="n">userids</span><span class="p">:</span>
<span class="n">uid</span> <span class="o">|=</span> <span class="n">mykey</span><span class="o">.</span><span class="n">certify</span><span class="p">(</span><span class="n">uid</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="verifying-things">
<h3>Verifying Things<a class="headerlink" href="#verifying-things" title="Permalink to this headline">¶</a></h3>
<p>Although signing things uses multiple methods, there is only one method to remember for verifying signatures:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># verify a detached signature</span>
<span class="n">pub</span><span class="o">.</span><span class="n">verify</span><span class="p">(</span><span class="s2">"I have just signed this text!"</span><span class="p">,</span> <span class="n">sig</span><span class="p">)</span>
<span class="c1"># verify signatures in a message</span>
<span class="n">pub</span><span class="o">.</span><span class="n">verify</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>
<span class="c1"># verify signatures on a userid</span>
<span class="k">for</span> <span class="n">uid</span> <span class="ow">in</span> <span class="n">someones_pubkey</span><span class="o">.</span><span class="n">userids</span><span class="p">:</span>
<span class="n">pub</span><span class="o">.</span><span class="n">verify</span><span class="p">(</span><span class="n">uid</span><span class="p">)</span>
<span class="c1"># or, better yet, verify all applicable signatures on a key in one go</span>
<span class="n">pub</span><span class="o">.</span><span class="n">verify</span><span class="p">(</span><span class="n">someones_pubkey</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="encryption">
<h3>Encryption<a class="headerlink" href="#encryption" title="Permalink to this headline">¶</a></h3>
<p>Another thing you may want to do is encrypt or decrypt messages.</p>
<div class="section" id="encrypting-decrypting-messages-with-a-public-key">
<h4>Encrypting/Decrypting Messages With a Public Key<a class="headerlink" href="#encrypting-decrypting-messages-with-a-public-key" title="Permalink to this headline">¶</a></h4>
<p>Encryption using keys requires a public key, while decryption requires a private key. PGPy currently only supports
asymmetric encryption/decryption using RSA:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># this returns a new PGPMessage that contains an encrypted form of the</span>
<span class="c1"># unencrypted message</span>
<span class="n">encrypted_message</span> <span class="o">=</span> <span class="n">rsa_pub</span><span class="o">.</span><span class="n">encrypt</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>
</pre></div>
</div>
<div class="section" id="encrypting-messages-to-multiple-recipients">
<h5>Encrypting Messages to Multiple Recipients<a class="headerlink" href="#encrypting-messages-to-multiple-recipients" title="Permalink to this headline">¶</a></h5>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Care must be taken when doing this to delete the session key as soon as possible after encrypting the message.</p>
</div>
<p>Messages can also be encrypted to multiple recipients by pre-generating the session key:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># The symmetric cipher should be specified, in case the first preferred cipher is not</span>
<span class="c1"># the same for all recipients' public keys</span>
<span class="n">cipher</span> <span class="o">=</span> <span class="n">pgpy</span><span class="o">.</span><span class="n">constants</span><span class="o">.</span><span class="n">SymmetricKeyAlgorithm</span><span class="o">.</span><span class="n">AES256</span>
<span class="n">sessionkey</span> <span class="o">=</span> <span class="n">cipher</span><span class="o">.</span><span class="n">gen_key</span><span class="p">()</span>
<span class="c1"># encrypt the message to multiple recipients</span>
<span class="c1"># A decryption passphrase can be added at any point as well, as long as cipher</span>
<span class="c1"># and sessionkey are also provided to enc_msg.encrypt</span>
<span class="n">enc_msg</span> <span class="o">=</span> <span class="n">pubkey1</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">cipher</span><span class="o">=</span><span class="n">cipher</span><span class="p">,</span> <span class="n">sessionkey</span><span class="o">=</span><span class="n">sessionkey</span><span class="p">)</span>
<span class="n">enc_msg</span> <span class="o">=</span> <span class="n">pubkey2</span><span class="o">.</span><span class="n">encrypt</span><span class="p">(</span><span class="n">enc_msg</span><span class="p">,</span> <span class="n">cipher</span><span class="o">=</span><span class="n">cipher</span><span class="p">,</span> <span class="n">sessionkey</span><span class="o">=</span><span class="n">sessionkey</span><span class="p">)</span>
<span class="c1"># do at least this as soon as possible after encrypting to the final recipient</span>
<span class="k">del</span> <span class="n">sessionkey</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="encrypting-decrypting-messages-with-a-passphrase">
<h4>Encrypting/Decrypting Messages With a Passphrase<a class="headerlink" href="#encrypting-decrypting-messages-with-a-passphrase" title="Permalink to this headline">¶</a></h4>
<p>There are some situations where encrypting a message with a passphrase may be more desirable than doing so with
someone else’s public key. That can be done like so:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># the .encrypt method returns a new PGPMessage object which contains the encrypted</span>
<span class="c1"># contents of the old message</span>
<span class="n">enc_message</span> <span class="o">=</span> <span class="n">message</span><span class="o">.</span><span class="n">encrypt</span><span class="p">(</span><span class="s2">"S00per_Sekr3t"</span><span class="p">)</span>
<span class="c1"># message.is_encrypted is False</span>
<span class="c1"># enc_message.is_encrypted is True</span>
<span class="c1"># a message that was encrypted using a passphrase can also be decrypted using</span>
<span class="c1"># that same passphrase</span>
<span class="n">dec_message</span> <span class="o">=</span> <span class="n">enc_message</span><span class="o">.</span><span class="n">decrypt</span><span class="p">(</span><span class="s2">"S00per_Sekr3t"</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
</div>
<div class="section" id="exporting-pgp-objects">
<h2>Exporting PGP* Objects<a class="headerlink" href="#exporting-pgp-objects" title="Permalink to this headline">¶</a></h2>
<p>PGPKey, PGPMessage, and PGPSignature objects can all be exported to OpenPGP-compatible binary and ASCII-armored formats.</p>
<p>To export in ASCII-armored format:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># This works in both Python 2.x and 3.x</span>
<span class="c1"># ASCII-armored format</span>
<span class="c1"># cleartext PGPMessages will also have properly canonicalized and dash-escaped</span>
<span class="c1"># message text</span>
<span class="n">pgpstr</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">pgpobj</span><span class="p">)</span>
</pre></div>
</div>
<p>To export to binary format in Python 3:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># binary format</span>
<span class="n">pgpbytes</span> <span class="o">=</span> <span class="nb">bytes</span><span class="p">(</span><span class="n">pgpobj</span><span class="p">)</span>
</pre></div>
</div>
<p>To export to binary format in Python 2:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># binary format</span>
<span class="n">pgpbytes</span> <span class="o">=</span> <span class="n">pgpobj</span><span class="o">.</span><span class="fm">__bytes__</span><span class="p">()</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Examples</a><ul>
<li><a class="reference internal" href="#keys">Keys</a><ul>
<li><a class="reference internal" href="#generating-keys">Generating Keys</a><ul>
<li><a class="reference internal" href="#generating-primary-keys">Generating Primary Keys</a></li>
<li><a class="reference internal" href="#generating-sub-keys">Generating Sub Keys</a></li>
</ul>
</li>
<li><a class="reference internal" href="#loading-keys">Loading Keys</a><ul>
<li><a class="reference internal" href="#loading-keys-individually">Loading Keys Individually</a></li>
<li><a class="reference internal" href="#loading-keys-into-a-keyring">Loading Keys Into a Keyring</a></li>
</ul>
</li>
<li><a class="reference internal" href="#key-operations">Key Operations</a><ul>
<li><a class="reference internal" href="#passphrase-protecting-secret-keys">Passphrase Protecting Secret Keys</a></li>
<li><a class="reference internal" href="#unlocking-protected-secret-keys">Unlocking Protected Secret Keys</a></li>
<li><a class="reference internal" href="#exporting-keys">Exporting Keys</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#messages">Messages</a><ul>
<li><a class="reference internal" href="#creating-new-messages">Creating New Messages</a></li>
<li><a class="reference internal" href="#loading-existing-messages">Loading Existing Messages</a></li>
<li><a class="reference internal" href="#exporting-messages">Exporting Messages</a></li>
</ul>
</li>
<li><a class="reference internal" href="#actions">Actions</a><ul>
<li><a class="reference internal" href="#signing-things">Signing Things</a><ul>
<li><a class="reference internal" href="#text-messages-other">Text/Messages/Other</a></li>
<li><a class="reference internal" href="#keys-user-ids">Keys/User IDs</a></li>
</ul>
</li>
<li><a class="reference internal" href="#verifying-things">Verifying Things</a></li>
<li><a class="reference internal" href="#encryption">Encryption</a><ul>
<li><a class="reference internal" href="#encrypting-decrypting-messages-with-a-public-key">Encrypting/Decrypting Messages With a Public Key</a><ul>
<li><a class="reference internal" href="#encrypting-messages-to-multiple-recipients">Encrypting Messages to Multiple Recipients</a></li>
</ul>
</li>
<li><a class="reference internal" href="#encrypting-decrypting-messages-with-a-passphrase">Encrypting/Decrypting Messages With a Passphrase</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#exporting-pgp-objects">Exporting PGP* Objects</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
<li>Previous: <a href="installation.html" title="previous chapter">Installation</a></li>
<li>Next: <a href="examples/keys.html" title="next chapter">Keys</a></li>
</ul></li>
</ul>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/examples.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©2018, Michael Greene.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
|
<a href="_sources/examples.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>
|