f5192f4cd82e517202f2113d8eb285c757c49471
[gpgme.git] / lang / python / docs / GPGMEpythonHOWTOen.org
1 #+TITLE: GNU Privacy Guard (GnuPG)  Made Easy Python Bindings HOWTO (English)
2 #+LATEX_COMPILER: xelatex
3 #+LATEX_CLASS: article
4 #+LATEX_CLASS_OPTIONS: [12pt]
5 #+LATEX_HEADER: \usepackage{xltxtra}
6 #+LATEX_HEADER: \usepackage[margin=1in]{geometry}
7 #+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Times New Roman}
8 #+LATEX_HEADER: \author{Ben McGinnes <ben@gnupg.org>}
9
10
11 * Introduction
12   :PROPERTIES:
13   :CUSTOM_ID: intro
14   :END:
15
16   | Version:        | 0.1.0-draft                              |
17   | Author:         | Ben McGinnes <ben@gnupg.org>             |
18   | Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
19   | Language:       | Australian English, British English      |
20   | xml:lang:       | en-AU, en-GB, en                         |
21
22   This document provides basic instruction in how to use the GPGME
23   Python bindings to programmatically leverage the GPGME library.
24
25
26 ** Python 2 versus Python 3
27    :PROPERTIES:
28    :CUSTOM_ID: py2-vs-py3
29    :END:
30
31    Though the GPGME Python bindings themselves provide support for
32    both Python 2 and 3, the focus is unequivocally on Python 3 and
33    specifically from Python 3.4 and above.  As a consequence all the
34    examples and instructions in this guide use Python 3 code.
35
36    Much of it will work with Python 2, but much of it also deals with
37    Python 3 byte literals, particularly when reading and writing data.
38    Developers concentrating on Python 2.7, and possibly even 2.6, will
39    need to make the appropriate modifications to support the older
40    string and unicode types as opposed to bytes.
41
42    There are multiple reasons for concentrating on Python 3; some of
43    which relate to the immediate integration of these bindings, some
44    of which relate to longer term plans for both GPGME and the python
45    bindings and some of which relate to the impending EOL period for
46    Python 2.7.  Essentially, though, there is little value in tying
47    the bindings to a version of the language which is a dead end and
48    the advantages offered by Python 3 over Python 2 make handling the
49    data types with which GPGME deals considerably easier.
50
51
52 * GPGME Concepts
53   :PROPERTIES:
54   :CUSTOM_ID: gpgme-concepts
55   :END:
56
57
58 ** A C API
59    :PROPERTIES:
60    :CUSTOM_ID: gpgme-c-api
61    :END:
62
63    Unlike many modern APIs with which programmers will be more
64    familiar with these days, the GPGME API is a C API.  The API is
65    intended for use by C coders who would be able to access its
66    features by including the =gpgme.h= header file with their own C
67    source code and then access its functions just as they would any
68    other C headers.
69
70    This is a very effective method of gaining complete access to the
71    API and in the most efficient manner possible.  It does, however,
72    have the drawback that it cannot be directly used by other
73    languages without some means of providing an interface to those
74    languages.  This is where the need for bindings in various
75    languages stems.
76
77
78 ** Python bindings
79    :PROPERTIES:
80    :CUSTOM_ID: gpgme-python-bindings
81    :END:
82
83    The Python bindings for GPGME provide a higher level means of
84    accessing the complete feature set of GPGME itself.  It also
85    provides a more pythonic means of calling these API functions.
86
87    The bindings are generated dynamically with SWIG and the copy of
88    =gpgme.h= generated when GPGME is compiled.
89
90    This means that a version of the Python bindings is fundamentally
91    tied to the exact same version of GPGME used to generate that copy
92    of =gpgme.h=.
93
94
95 ** Difference between the Python bindings and other GnuPG Python packages
96    :PROPERTIES:
97    :CUSTOM_ID: gpgme-python-bindings-diffs
98    :END:
99
100    There have been numerous attempts to add GnuPG support to Python
101    over the years.  Some of the most well known are listed here, along
102    with what differentiates them.
103
104
105 *** The python-gnupg package maintained by Vinay Sajip
106     :PROPERTIES:
107     :CUSTOM_ID: diffs-python-gnupg
108     :END:
109
110     This is arguably the most popular means of integrating GPG with
111     Python.  The package utilises the =subprocess= module to implement
112     wrappers for the =gpg= and =gpg2= executables normally invoked on
113     the command line (=gpg.exe= and =gpg2.exe= on Windows).
114
115     The popularity of this package stemmed from its ease of use and
116     capability in providing the most commonly required features.
117
118     Unfortunately it has been beset by a number of security issues,
119     most of which stemmed from using unsafe methods of accessing the
120     command line via the =subprocess= calls.
121
122     The python-gnupg package is available under the MIT license.
123
124
125 *** The gnupg package created and maintained by Isis Lovecruft
126     :PROPERTIES:
127     :CUSTOM_ID: diffs-isis-gnupg
128     :END:
129
130     In 2015 Isis Lovecruft from the Tor Project forked and then
131     re-implemented the python-gnupg package as just gnupg.  This new
132     package also relied on subprocess to call the =gpg= or =gpg2=
133     binaries, but did so somewhat more securely.
134
135     However the naming and version numbering selected for this package
136     resulted in conflicts with the original python-gnupg and since its
137     functions were called in a different manner, the release of this
138     package also resulted in a great deal of consternation when people
139     installed what they thought was an upgrade that subsequently broke
140     the code relying on it.
141
142     The gnupg package is available under the GNU General Public
143     License version 3.0 (or later).
144
145
146 *** The PyME package maintained by Martin Albrecht
147     :PROPERTIES:
148     :CUSTOM_ID: diffs-pyme
149     :END:
150
151     This package is the origin of these bindings, though they are
152     somewhat different now.  For details of when and how the PyME
153     package was folded back into GPGME itself see the /Short History/
154     document[fn:1] in this Python bindings =docs= directory.[fn:2]
155
156     The PyME package was first released in 2002 and was also the first
157     attempt to implement a low level binding to GPGME.  In doing so it
158     provided access to considerably more functionality than either the
159     =python-gnupg= or =gnupg= packages.
160
161     The PyME package is only available for Python 2.6 and 2.7.
162
163     Porting the PyME package to Python 3.4 in 2015 is what resulted in
164     it being folded into the GPGME project and the current bindings
165     are the end result of that effort.
166
167     The PyME package is available under the same dual licensing as
168     GPGME itself: the GNU General Public License version 2.0 (or any
169     later version) and the GNU Lesser General Public License version
170     2.1 (or any later version).
171
172
173 * GPGME Python bindings installation
174   :PROPERTIES:
175   :CUSTOM_ID: gpgme-python-install
176   :END:
177
178
179 ** No PyPI
180    :PROPERTIES:
181    :CUSTOM_ID: do-not-use-pypi
182    :END:
183
184    Most third-party Python packages and modules are available and
185    distributed through the Python Package Installer, known as PyPI.
186
187    Due to the nature of what these bindings are and how they work, it
188    is infeasible to install the GPGME Python bindings in the same way.
189
190    This is because the bindings use SWIG to dynamically generate C
191    bindings against =gpgme.h= and =gpgme.h= is generated from
192    =gpgme.h.in= at compile time when GPGME is built from source.  Thus
193    to include a package in PyPI which actually built correctly would
194    require either statically built libraries for every architecture
195    bundled with it or a full implementation of C for each
196    architecture.
197
198
199 ** Requirements
200    :PROPERTIES:
201    :CUSTOM_ID: gpgme-python-requirements
202    :END:
203
204    The GPGME Python bindings only have three requirements:
205
206    1. A suitable version of Python 2 or Python 3.  With Python 2 that
207       means Python 2.7 and with Python 3 that means Python 3.4 or
208       higher.
209    2. SWIG.
210    3. GPGME itself.  Which also means that all of GPGME's dependencies
211       must be installed too.
212
213
214 ** Installation
215    :PROPERTIES:
216    :CUSTOM_ID: installation
217    :END:
218
219    Installing the Python bindings is effectively achieved by compiling
220    and installing GPGME itself.
221
222    Once SWIG is installed with Python and all the dependencies for
223    GPGME are installed you only need to confirm that the version(s) of
224    Python you want the bindings installed for are in your =$PATH=.
225
226    By default GPGME will attempt to install the bindings for the most
227    recent or highest version number of Python 2 and Python 3 it
228    detects in =$PATH=.  It specifically checks for the =python= and
229    =python3= executables first and then checks for specific version
230    numbers.
231
232    For Python 2 it checks for these executables in this order:
233    =python=, =python2= and =python2.7=.
234
235    For Python 3 it checks for these executables in this order:
236    =python3=, =python3.6=, =python3.5= and =python3.4=.
237
238
239 *** Installing GPGME
240     :PROPERTIES:
241     :CUSTOM_ID: install-gpgme
242     :END:
243
244     See the GPGME =README= file for details of how to install GPGME from
245     source.
246
247
248 * Fundamentals
249   :PROPERTIES:
250   :CUSTOM_ID: howto-fund-a-mental
251   :END:
252
253   Before we can get to the fun stuff, there are a few matters
254   regarding GPGME's design which hold true whether you're dealing with
255   the C code directly or these Python bindings.
256
257
258 ** No REST
259    :PROPERTIES:
260    :CUSTOM_ID: no-rest-for-the-wicked
261    :END:
262
263    The first part of which is or will be fairly blatantly obvious upon
264    viewing the first example, but it's worth reiterating anyway.  That
265    being that this API is /*not*/ a REST API.  Nor indeed could it
266    ever be one.
267
268    Most, if not all, Python programmers (and not just Python
269    programmers) know how easy it is to work with a RESTful API.  In
270    fact they've become so popular that many other APIs attempt to
271    emulate REST-like behaviour as much as they are able.  Right down
272    to the use of JSON formatted output to facilitate the use of their
273    API without having to retrain developers.
274
275    This API does not do that.  It would not be able to do that and
276    also provide access to the entire C API on which it's built.  It
277    does, however, provide a very pythonic interface on top of the
278    direct bindings and it's this pythonic layer with which this HOWTO
279    deals with.
280
281
282 ** Context
283    :PROPERTIES:
284    :CUSTOM_ID: howto-get-context
285    :END:
286
287    One of the reasons which prevents this API from being RESTful is
288    that most operations require more than one instruction to the API
289    to perform the task.  Sure, there are certain functions which can
290    be performed simultaneously, particularly if the result known or
291    strongly anticipated (e.g. selecting and encrypting to a key known
292    to be in the public keybox).
293
294    There are many more, however, which cannot be manipulated so
295    readily: they must be performed in a specific sequence and the
296    result of one operation has a direct bearing on the outcome of
297    subsequent operations.  Not merely by generating an error either.
298
299    When dealing with this type of persistent state on the web, full of
300    both the RESTful and REST-like, it's most commonly referred to as a
301    session.  In GPGME, however, it is called a context and every
302    operation type has one.
303
304
305 * Working with keys
306   :PROPERTIES:
307   :CUSTOM_ID: howto-keys
308   :END:
309
310
311 ** Key selection
312    :PROPERTIES:
313    :CUSTOM_ID: howto-keys-selection
314    :END:
315
316    Selecting keys to encrypt to or to sign with will be a common
317    occurrence when working with GPGMe and the means available for
318    doing so are quite simple.
319
320    They do depend on utilising a Context; however once the data is
321    recorded in another variable, that Context does not need to be the
322    same one which subsequent operations are performed.
323
324    The easiest way to select a specific key is by searching for that
325    key's key ID or fingerprint, preferably the full fingerprint
326    without any spaces in it.  A long key ID will probably be okay, but
327    is not advised and short key IDs are already a problem with some
328    being generated to match specific patterns.  It does not matter
329    whether the pattern is upper or lower case.
330
331    So this is the best method:
332
333    #+begin_src python
334      import gpg
335
336      k = gpg.Context().keylist(pattern="258E88DCBD3CD44D8E7AB43F6ECB6AF0DEADBEEF")
337      keys = list(k)
338    #+end_src
339
340    This is passable and very likely to be common:
341
342    #+begin_src python
343      import gpg
344
345      k = gpg.Context().keylist(pattern="0x6ECB6AF0DEADBEEF")
346      keys = list(k)
347    #+end_src
348
349    And this is a really bad idea:
350
351    #+begin_src python
352      import gpg
353
354      k = gpg.Context().keylist(pattern="0xDEADBEEF")
355      keys = list(k)
356    #+end_src
357
358    Alternatively it may be that the intention is to create a list of
359    keys which all match a particular search string.  For instance all
360    the addresses at a particular domain, like this:
361
362    #+begin_src python
363      import gpg
364
365      ncsc = gpg.Context().keylist(pattern="ncsc.mil")
366      nsa = list(ncsc)
367    #+end_src
368
369
370 *** Counting keys
371     :PROPERTIES:
372     :CUSTOM_ID: howto-keys-counting
373     :END:
374
375     Counting the number of keys in your public keybox (=pubring.kbx=),
376     the format which has superseded the old keyring format
377     (=pubring.gpg= and =secring.gpg=), or the number of secret keys is
378     a very simple task.
379
380     #+begin_src python
381       import gpg
382
383       c = gpg.Context()
384       seckeys = c.keylist(pattern=None, secret=True)
385       pubkeys = c.keylist(pattern=None, secret=False)
386
387       seclist = list(seckeys)
388       secnum = len(seclist)
389
390       publist = list(pubkeys)
391       pubnum = len(publist)
392
393       print("""
394       Number of secret keys:  {0}
395       Number of public keys:  {1}
396       """.format(secnum, pubnum)
397     #+end_src
398
399
400 ** Get key
401    :PROPERTIES:
402    :CUSTOM_ID: howto-get-key
403    :END:
404
405    An alternative method of getting a single key via its fingerprint
406    is available directly within a Context with =Context().get_key=.
407    This is the preferred method of selecting a key in order to modify
408    it, sign or certify it and for obtaining relevant data about a
409    single key as a part of other functions; when verifying a signature
410    made by that key, for instance.
411
412    By default this method will select public keys, but it can select
413    secret keys as well.
414
415    This first example demonstrates selecting the current key of Werner
416    Koch, which is due to expire at the end of 2018:
417
418    #+begin_src python
419      import gpg
420
421      fingerprint = "80615870F5BAD690333686D0F2AD85AC1E42B367"
422      key = gpg.Context().get_key(fingerprint)
423    #+end_src
424
425    Whereas this example demonstrates selecting the author's current
426    key with the =secret= key word argument set to =True=:
427
428    #+begin_src python
429      import gpg
430
431      fingerprint = "DB4724E6FA4286C92B4E55C4321E4E2373590E5D"
432      key = gpg.Context().get_key(fingerprint, secret=True)
433    #+end_src
434
435    It is, of course, quite possible to select expired, disabled and
436    revoked keys with this function, but only to effectively display
437    information about those keys.
438
439    It is also possible to use both unicode or string literals and byte
440    literals with the fingerprint when getting a key in this way.
441
442
443 * Basic Functions
444   :PROPERTIES:
445   :CUSTOM_ID: howto-the-basics
446   :END:
447
448   The most frequently called features of any cryptographic library
449   will be the most fundamental tasks for encryption software.  In this
450   section we will look at how to programmatically encrypt data,
451   decrypt it, sign it and verify signatures.
452
453
454 ** Encryption
455    :PROPERTIES:
456    :CUSTOM_ID: howto-basic-encryption
457    :END:
458
459    Encrypting is very straight forward.  In the first example below
460    the message, =text=, is encrypted to a single recipient's key.  In
461    the second example the message will be encrypted to multiple
462    recipients.
463
464
465 *** Encrypting to one key
466     :PROPERTIES:
467     :CUSTOM_ID: howto-basic-encryption-single
468     :END:
469
470     Once the the Context is set the main issues with encrypting data
471     is essentially reduced to key selection and the keyword arguments
472     specified in the =gpg.Context().encrypt()= method.
473
474     Those keyword arguments are: =recipients=, a list of keys
475     encrypted to (covered in greater detail in the following section);
476     =sign=, whether or not to sign the plaintext data, see subsequent
477     sections on signing and verifying signatures below (defaults to
478     =True=); =sink=, to write results or partial results to a secure
479     sink instead of returning it (defaults to =None=); =passphrase=,
480     only used when utilising symmetric encryption (defaults to
481     =None=); =always_trust=, used to override the trust model settings
482     for recipient keys (defaults to =False=); =add_encrypt_to=,
483     utilises any preconfigured =encrypt-to= or =default-key= settings
484     in the user's =gpg.conf= file (defaults to =False=); =prepare=,
485     prepare for encryption (defaults to =False=); =expect_sign=,
486     prepare for signing (defaults to =False=); =compress=, compresses
487     the plaintext prior to encryption (defaults to =True=).
488
489     #+begin_src python
490       import gpg
491
492       a_key = "0x12345678DEADBEEF"
493       text = b"""Some text to test with.
494
495       Since the text in this case must be bytes, it is most likely that
496       the input form will be a separate file which is opened with "rb"
497       as this is the simplest method of obtaining the correct data
498       format.
499       """
500
501       c = gpg.Context(armor=True)
502       rkey = list(c.keylist(pattern=a_key, secret=False))
503       ciphertext, result, sign_result = c.encrypt(text, recipients=rkey, sign=False)
504
505       with open("secret_plans.txt.asc", "wb") as afile:
506           afile.write(ciphertext)
507     #+end_src
508
509     Though this is even more likely to be used like this; with the
510     plaintext input read from a file, the recipient keys used for
511     encryption regardless of key trust status and the encrypted output
512     also encrypted to any preconfigured keys set in the =gpg.conf=
513     file:
514
515     #+begin_src python
516       import gpg
517
518       a_key = "0x12345678DEADBEEF"
519
520       with open("secret_plans.txt", "rb") as afile:
521           text = afile.read()
522
523       c = gpg.Context(armor=True)
524       rkey = list(c.keylist(pattern=a_key, secret=False))
525       ciphertext, result, sign_result = c.encrypt(text, recipients=rkey,
526                                                   sign=True, always_trust=True,
527                                                   add_encrypt_to=True)
528
529       with open("secret_plans.txt.asc", "wb") as afile:
530           afile.write(ciphertext)
531     #+end_src
532
533     If the =recipients= paramater is empty then the plaintext is
534     encrypted symmetrically.  If no =passphrase= is supplied as a
535     parameter or via a callback registered with the =Context()= then
536     an out-of-band prompt for the passphrase via pinentry will be
537     invoked.
538
539
540 *** Encrypting to multiple keys
541     :PROPERTIES:
542     :CUSTOM_ID: howto-basic-encryption-multiple
543     :END:
544
545     Encrypting to multiple keys essentially just expands upon the key
546     selection process and the recipients from the previous examples.
547
548     The following example encrypts a message (=text=) to everyone with
549     an email address on the =gnupg.org= domain,[fn:3] but does /not/ encrypt
550     to a default key or other key which is configured to normally
551     encrypt to.
552
553     #+begin_src python
554       import gpg
555
556       text = b"""Oh look, another test message.
557
558       The same rules apply as with the previous example and more likely
559       than not, the message will actually be drawn from reading the
560       contents of a file or, maybe, from entering data at an input()
561       prompt.
562
563       Since the text in this case must be bytes, it is most likely that
564       the input form will be a separate file which is opened with "rb"
565       as this is the simplest method of obtaining the correct data
566       format.
567       """
568
569       c = gpg.Context(armor=True)
570       rpattern = list(c.keylist(pattern="@gnupg.org", secret=False))
571       logrus = []
572
573       for i in range(len(rpattern)):
574           if rpattern[i].can_encrypt == 1:
575               logrus.append(rpattern[i])
576
577       ciphertext, result, sign_result = c.encrypt(text, recipients=logrus, sign=False,
578                                                   always_trust=True)
579
580       with open("secret_plans.txt.asc", "wb") as afile:
581           afile.write(ciphertext)
582     #+end_src
583
584     All it would take to change the above example to sign the message
585     and also encrypt the message to any configured default keys would
586     be to change the =c.encrypt= line to this:
587
588     #+begin_src python
589       ciphertext, result, sign_result = c.encrypt(text, recipients=logrus,
590                                                   always_trust=True,
591                                                   add_encrypt_to=True)
592     #+end_src
593
594     The only keyword arguments requiring modification are those for
595     which the default values are changing.  The default value of
596     =sign= is =True=, the default of =always_trust= is =False=, the
597     default of =add_encrypt_to= is =False=.
598
599     If =always_trust= is not set to =True= and any of the recipient
600     keys are not trusted (e.g. not signed or locally signed) then the
601     encryption will raise an error.  It is possible to mitigate this
602     somewhat with something more like this:
603
604     #+begin_src python
605       import gpg
606
607       with open("secret_plans.txt.asc", "rb") as afile:
608           text = afile.read()
609
610       c = gpg.Context(armor=True)
611       rpattern = list(c.keylist(pattern="@gnupg.org", secret=False))
612       logrus = []
613
614       for i in range(len(rpattern)):
615           if rpattern[i].can_encrypt == 1:
616               logrus.append(rpattern[i])
617
618       try:
619           ciphertext, result, sign_result = c.encrypt(text, recipients=logrus, add_encrypt_to=True)
620       except gpg.errors.InvalidRecipients as e:
621           for i in range(len(e.recipients)):
622               for n in range(len(logrus)):
623                   if logrus[n].fpr == e.recipients[i].fpr:
624                       logrus.remove(logrus[n])
625                   else:
626                       pass
627           try:
628               ciphertext, result, sign_result = c.encrypt(text, recipients=logrus, add_encrypt_to=True)
629           except:
630               pass
631
632       with open("secret_plans.txt.asc", "wb") as afile:
633           afile.write(ciphertext)
634     #+end_src
635
636     This will attempt to encrypt to all the keys searched for, then
637     remove invalid recipients if it fails and try again.
638
639
640 ** Decryption
641    :PROPERTIES:
642    :CUSTOM_ID: howto-basic-decryption
643    :END:
644
645    Decrypting something encrypted to a key in one's secret keyring is
646    fairly straight forward.
647
648    In this example code, however, preconfiguring either
649    =gpg.Context()= or =gpg.core.Context()= as =c= is unnecessary
650    because there is no need to modify the Context prior to conducting
651    the decryption and since the Context is only used once, setting it
652    to =c= simply adds lines for no gain.
653
654    #+begin_src python
655      import gpg
656
657      ciphertext = input("Enter path and filename of encrypted file: ")
658      newfile = input("Enter path and filename of file to save decrypted data to: ")
659      with open(ciphertext, "rb") as cfile:
660          plaintext, result, verify_result = gpg.Context().decrypt(cfile)
661      with open(newfile, "wb" as nfile:
662          nfile.write(plaintext)
663    #+end_src
664
665    The data available in plaintext in this example is the decrypted
666    content as a byte object in =plaintext[0]=, the recipient key IDs
667    and algorithms in =plaintext[1]= and the results of verifying any
668    signatures of the data in =plaintext[0]=.
669
670
671 ** Signing text and files
672    :PROPERTIES:
673    :CUSTOM_ID: howto-basic-signing
674    :END:
675
676    The following sections demonstrate how to specify keys to sign with.
677
678
679 *** Signing key selection
680     :PROPERTIES:
681     :CUSTOM_ID: howto-basic-signing-signers
682     :END:
683
684     By default GPGME and the Python bindings will use the default key
685     configured for the user invoking the GPGME API.  If there is no
686     default key specified and there is more than one secret key
687     available it may be necessary to specify the key or keys with
688     which to sign messages and files.
689
690     #+begin_src python
691       import gpg
692
693       logrus = input("Enter the email address or string to match signing keys to: ")
694       hancock = gpg.Context().keylist(pattern=logrus, secret=True)
695       sig_src = list(hancock)
696     #+end_src
697
698     The signing examples in the following sections include the
699     explicitly designated =signers= parameter in two of the five
700     examples; once where the resulting signature would be ASCII
701     armoured and once where it would not be armoured.
702
703     While it would be possible to enter a key ID or fingerprint here
704     to match a specific key, it is not possible to enter two
705     fingerprints and match two keys since the patten expects a string,
706     bytes or None and not a list.  A string with two fingerprints
707     won't match any single key.
708
709
710 *** Normal or default signing messages or files
711     :PROPERTIES:
712     :CUSTOM_ID: howto-basic-signing-normal
713     :END:
714
715     The normal or default signing process is essentially the same as
716     is most often invoked when also encrypting a message or file.  So
717     when the encryption component is not utilised, the result is to
718     produce an encoded and signed output which may or may not be ASCII
719     armoured and which may or may not also be compressed.
720
721     By default compression will be used unless GnuPG detects that the
722     plaintext is already compressed.  ASCII armouring will be
723     determined according to the value of =gpg.Context().armor=.
724
725     The compression algorithm is selected in much the same way as the
726     symmetric encryption algorithm or the hash digest algorithm is
727     when multiple keys are involved; from the preferences saved into
728     the key itself or by comparison with the preferences with all
729     other keys involved.
730
731    #+begin_src python
732      import gpg
733
734      text0 = """Declaration of ... something.
735
736      """
737      text = text0.encode()
738
739      c = gpg.Context(armor=True, signers=sig_src)
740      signed = c.sign(text, mode=gpg.constants.sig.mode.NORMAL)
741
742      with open("/path/to/statement.txt.asc", "w") as afile:
743          for line in signed[0]:
744              afile.write("{0}\n".format(line.decode()))
745    #+end_src
746
747    Though everything in this example is accurate, it is more likely
748    that reading the input data from another file and writing the
749    result to a new file will be performed more like the way it is done
750    in the next example.  Even if the output format is ASCII armoured.
751
752    #+begin_src python
753      import gpg
754
755      with open("/path/to/statement.txt", "rb") as tfile:
756          text = tfile.read()
757
758      c = gpg.Context()
759      signed = c.sign(text, mode=gpg.constants.sig.mode.NORMAL)
760
761      with open("/path/to/statement.txt.sig", "wb") as afile:
762          afile.write(signed[0])
763    #+end_src
764
765
766 *** Detached signing messages and files
767     :PROPERTIES:
768     :CUSTOM_ID: howto-basic-signing-detached
769     :END:
770
771     Detached signatures will often be needed in programmatic uses of
772     GPGME, either for signing files (e.g. tarballs of code releases)
773     or as a component of message signing (e.g. PGP/MIME encoded
774     email).
775
776     #+begin_src python
777       import gpg
778
779       text0 = """Declaration of ... something.
780
781       """
782       text = text0.encode()
783
784       c = gpg.Context(armor=True)
785       signed = c.sign(text, mode=gpg.constants.sig.mode.DETACH)
786
787       with open("/path/to/statement.txt.asc", "w") as afile:
788           for line in signed[0].splitlines():
789               afile.write("{0}\n".format(line.decode()))
790     #+end_src
791
792     As with normal signatures, detached signatures are best handled as
793     byte literals, even when the output is ASCII armoured.
794
795     #+begin_src python
796       import gpg
797
798       with open("/path/to/statement.txt", "rb") as tfile:
799           text = tfile.read()
800
801       c = gpg.Context(signers=sig_src)
802       signed = c.sign(text, mode=gpg.constants.sig.mode.DETACH)
803
804       with open("/path/to/statement.txt.sig", "wb") as afile:
805           afile.write(signed[0])
806     #+end_src
807
808
809 *** Clearsigning messages or text
810     :PROPERTIES:
811     :CUSTOM_ID: howto-basic-signing-clear
812     :END:
813
814     Though PGP/in-line messages are no longer encouraged in favour of
815     PGP/MIME, there is still sometimes value in utilising in-line
816     signatures.  This is where clear-signed messages or text is of
817     value.
818
819     #+begin_src python
820       import gpg
821
822       text0 = """Declaration of ... something.
823
824       """
825       text = text0.encode()
826
827       c = gpg.Context()
828       signed = c.sign(text, mode=gpg.constants.sig.mode.CLEAR)
829
830       with open("/path/to/statement.txt.asc", "w") as afile:
831           for line in signed[0].splitlines():
832               afile.write("{0}\n".format(line.decode()))
833     #+end_src
834
835     In spite of the appearance of a clear-signed message, the data
836     handled by GPGME in signing it must still be byte literals.
837
838     #+begin_src python
839       import gpg
840
841       with open("/path/to/statement.txt", "rb") as tfile:
842           text = tfile.read()
843
844       c = gpg.Context()
845       signed = c.sign(text, mode=gpg.constants.sig.mode.CLEAR)
846
847       with open("/path/to/statement.txt.asc", "wb") as afile:
848           afile.write(signed[0])
849     #+end_src
850
851
852 ** Signature verification
853    :PROPERTIES:
854    :CUSTOM_ID: howto-basic-verification
855    :END:
856
857    Essentially there are two principal methods of verification of a
858    signature.  The first of these is for use with the normal or
859    default signing method and for clear-signed messages.  The second is
860    for use with files and data with detached signatures.
861
862    The following example is intended for use with the default signing
863    method where the file was not ASCII armoured:
864
865    #+begin_src python
866      import gpg
867      import time
868
869      filename = "statement.txt"
870      gpg_file = "statement.txt.gpg"
871
872      c = gpg.Context()
873
874      try:
875          data, result = c.verify(open(gpg_file))
876          verified = True
877      except gpg.errors.BadSignatures as e:
878          verified = False
879          print(e)
880
881      if verified is True:
882          for i in range(len(result.signatures)):
883              sign = result.signatures[i]
884              print("""Good signature from:
885      {0}
886      with key {1}
887      made at {2}
888      """.format(c.get_key(sign.fpr).uids[0].uid,
889                 sign.fpr, time.ctime(sign.timestamp)))
890      else:
891          pass(e)
892    #+end_src
893
894    Whereas this next example, which is almost identical would work
895    with normal ASCII armoured files and with clear-signed files:
896
897    #+begin_src python
898      import gpg
899      import time
900
901      filename = "statement.txt"
902      asc_file = "statement.txt.asc"
903
904      c = gpg.Context()
905
906      try:
907          data, result = c.verify(open(asc_file))
908          verified = True
909      except gpg.errors.BadSignatures as e:
910          verified = False
911          print(e)
912
913      if verified is True:
914          for i in range(len(result.signatures)):
915              sign = result.signatures[i]
916              print("""Good signature from:
917      {0}
918      with key {1}
919      made at {2}
920      """.format(c.get_key(sign.fpr).uids[0].uid,
921                 sign.fpr, time.ctime(sign.timestamp)))
922      else:
923          pass
924    #+end_src
925
926    In both of the previous examples it is also possible to compare the
927    original data that was signed against the signed data in =data= to
928    see if it matches with something like this:
929
930    #+begin_src python
931      with open(filename, "rb") as afile:
932          text = afile.read()
933
934      if text == data:
935          print("Good signature.")
936      else:
937          pass
938    #+end_src
939
940    The following two examples, however, deal with detached signatures.
941    With his method of verification the data that was signed does not
942    get returned since it is already being explicitly referenced in the
943    first argument of =c.verify=.  So =data= is =None= and only the
944    information in =result= is available.
945
946    #+begin_src python
947      import gpg
948      import time
949
950      filename = "statement.txt"
951      sig_file = "statement.txt.sig"
952
953      c = gpg.Context()
954
955      try:
956          data, result = c.verify(open(filename), open(sig_file))
957          verified = True
958      except gpg.errors.BadSignatures as e:
959          verified = False
960          print(e)
961
962      if verified is True:
963          for i in range(len(result.signatures)):
964              sign = result.signatures[i]
965              print("""Good signature from:
966      {0}
967      with key {1}
968      made at {2}
969      """.format(c.get_key(sign.fpr).uids[0].uid,
970                 sign.fpr, time.ctime(sign.timestamp)))
971      else:
972          pass
973    #+end_src
974
975    #+begin_src python
976      import gpg
977      import time
978
979      filename = "statement.txt"
980      asc_file = "statement.txt.asc"
981
982      c = gpg.Context()
983
984      try:
985          data, result = c.verify(open(filename), open(asc_file))
986          verified = True
987      except gpg.errors.BadSignatures as e:
988          verified = False
989          print(e)
990
991      if verified is not None:
992          for i in range(len(result.signatures)):
993              sign = result.signatures[i]
994              print("""Good signature from:
995      {0}
996      with key {1}
997      made at {2}
998      """.format(c.get_key(sign.fpr).uids[0].uid,
999                 sign.fpr, time.ctime(sign.timestamp)))
1000      else:
1001          pass
1002    #+end_src
1003
1004
1005 * Creating keys and subkeys
1006   :PROPERTIES:
1007   :CUSTOM_ID: key-generation
1008   :END:
1009
1010   The one thing, aside from GnuPG itself, that GPGME depends on, of
1011   course, is the keys themselves.  So it is necessary to be able to
1012   generate them and modify them by adding subkeys, revoking or
1013   disabling them, sometimes deleting them and doing the same for user
1014   IDs.
1015
1016   In the following examples a key will be created for the world's
1017   greatest secret agent, Danger Mouse.  Since Danger Mouse is a secret
1018   agent he needs to be able to protect information to =SECRET= level
1019   clearance, so his keys will be 3072-bit keys.
1020
1021   The pre-configured =gpg.conf= file which sets cipher, digest and
1022   other preferences contains the following configuration parameters:
1023
1024   #+begin_src conf
1025     expert
1026     allow-freeform-uid
1027     allow-secret-key-import
1028     trust-model tofu+pgp
1029     tofu-default-policy unknown
1030     enable-large-rsa
1031     enable-dsa2
1032     # cert-digest-algo SHA256
1033     cert-digest-algo SHA512
1034     default-preference-list TWOFISH CAMELLIA256 AES256 CAMELLIA192 AES192 CAMELLIA128 AES BLOWFISH IDEA CAST5 3DES SHA512 SHA384 SHA256 SHA224 RIPEMD160 SHA1 ZLIB BZIP2 ZIP Uncompressed
1035     personal-cipher-preferences TWOFISH CAMELLIA256 AES256 CAMELLIA192 AES192 CAMELLIA128 AES BLOWFISH IDEA CAST5 3DES
1036     personal-digest-preferences SHA512 SHA384 SHA256 SHA224 RIPEMD160 SHA1
1037     personal-compress-preferences ZLIB BZIP2 ZIP Uncompressed
1038   #+end_src
1039
1040
1041 ** Primary key
1042    :PROPERTIES:
1043    :CUSTOM_ID: keygen-primary
1044    :END:
1045
1046    Generating a primary key uses the =create_key= method in a Context.
1047    It contains multiple arguments and keyword arguments, including:
1048    =userid=, =algorithm=, =expires_in=, =expires=, =sign=, =encrypt=,
1049    =certify=, =authenticate=, =passphrase= and =force=.  The defaults
1050    for all of those except =userid=, =algorithm=, =expires_in=,
1051    =expires= and =passphrase= is =False=.  The defaults for
1052    =algorithm= and =passphrase= is =None=.  The default for
1053    =expires_in= is =0=.  The default for =expires= is =True=.  There
1054    is no default for =userid=.
1055
1056    If =passphrase= is left as =None= then the key will not be
1057    generated with a passphrase, if =passphrase= is set to a string
1058    then that will be the passphrase and if =passphrase= is set to
1059    =True= then gpg-agent will launch pinentry to prompt for a
1060    passphrase.  For the sake of convenience, these examples will keep
1061    =passphrase= set to =None=.
1062
1063    #+begin_src python
1064      import gpg
1065
1066      c = gpg.Context()
1067
1068      c.home_dir = "~/.gnupg-dm"
1069      userid = "Danger Mouse <dm@secret.example.net>"
1070
1071      dmkey = c.create_key(userid, algorithm = "rsa3072", expires_in = 31536000,
1072                           sign = True, certify = True)
1073    #+end_src
1074
1075    One thing to note here is the use of setting the =c.home_dir=
1076    parameter.  This enables generating the key or keys in a different
1077    location.  In this case to keep the new key data created for this
1078    example in a separate location rather than adding it to existing
1079    and active key store data.  As with the default directory,
1080    =~/.gnupg=, any temporary or separate directory needs the
1081    permissions set to only permit access by the directory owner.  On
1082    posix systems this means setting the directory permissions to 700.
1083
1084    The successful generation of the key can be confirmed via the
1085    returned =GenkeyResult= object, which includes the following data:
1086
1087    #+begin_src python
1088      print("""
1089      Fingerprint:  {0}
1090      Primary Key:  {1}
1091       Public Key:  {2}
1092       Secret Key:  {3}
1093          Sub Key:  {4}
1094         User IDs:  {5}
1095      """.format(dmkey.fpr, dmkey.primary, dmkey.pubkey, dmkey.seckey, dmkey.sub,
1096                 dmkey.uid))
1097    #+end_src
1098
1099    Alternatively the information can be confirmed using the command
1100    line program:
1101
1102    #+begin_src shell
1103      bash-4.4$ gpg --homedir ~/.gnupg-dm -K
1104      ~/.gnupg-dm/pubring.kbx
1105      ----------------------
1106      sec   rsa3072 2018-03-15 [SC] [expires: 2019-03-15]
1107            177B7C25DB99745EE2EE13ED026D2F19E99E63AA
1108      uid           [ultimate] Danger Mouse <dm@secret.example.net>
1109
1110      bash-4.4$
1111    #+end_src
1112
1113    As with generating keys manually, to preconfigure expanded
1114    preferences for the cipher, digest and compression algorithms, the
1115    =gpg.conf= file must contain those details in the home directory in
1116    which the new key is being generated.  I used a cut down version of
1117    my own =gpg.conf= file in order to be able to generate this:
1118
1119    #+begin_src shell
1120      bash-4.4$ gpg --homedir ~/.gnupg-dm --edit-key 177B7C25DB99745EE2EE13ED026D2F19E99E63AA showpref quit
1121      Secret key is available.
1122
1123      sec  rsa3072/026D2F19E99E63AA
1124           created: 2018-03-15  expires: 2019-03-15  usage: SC
1125           trust: ultimate      validity: ultimate
1126      [ultimate] (1). Danger Mouse <dm@secret.example.net>
1127
1128      [ultimate] (1). Danger Mouse <dm@secret.example.net>
1129           Cipher: TWOFISH, CAMELLIA256, AES256, CAMELLIA192, AES192, CAMELLIA128, AES, BLOWFISH, IDEA, CAST5, 3DES
1130           Digest: SHA512, SHA384, SHA256, SHA224, RIPEMD160, SHA1
1131           Compression: ZLIB, BZIP2, ZIP, Uncompressed
1132           Features: MDC, Keyserver no-modify
1133
1134      bash-4.4$
1135    #+end_src
1136
1137
1138 ** Subkeys
1139    :PROPERTIES:
1140    :CUSTOM_ID: keygen-subkeys
1141    :END:
1142
1143    Adding subkeys to a primary key is fairly similar to creating the
1144    primary key with the =create_subkey= method.  Most of the arguments
1145    are the same, but not quite all.  Instead of the =userid= argument
1146    there is now a =key= argument for selecting which primary key to
1147    add the subkey to.
1148
1149    In the following example an encryption subkey will be added to the
1150    primary key.  Since Danger Mouse is a security conscious secret
1151    agent, this subkey will only be valid for about six months, half
1152    the length of the primary key.
1153
1154    #+begin_src python
1155      import gpg
1156
1157      c = gpg.Context()
1158      c.home_dir = "~/.gnupg-dm"
1159
1160      key = c.get_key(dmkey.fpr, secret = True)
1161      dmsub = c.create_subkey(key, algorithm = "rsa3072", expires_in = 15768000,
1162                              encrypt = True)
1163    #+end_src
1164
1165    As with the primary key, the results here can be checked with:
1166
1167    #+begin_src python
1168      print("""
1169      Fingerprint:  {0}
1170      Primary Key:  {1}
1171       Public Key:  {2}
1172       Secret Key:  {3}
1173          Sub Key:  {4}
1174         User IDs:  {5}
1175      """.format(dmsub.fpr, dmsub.primary, dmsub.pubkey, dmsub.seckey, dmsub.sub,
1176                 dmsub.uid))
1177    #+end_src
1178
1179    As well as on the command line with:
1180
1181    #+begin_src shell
1182      bash-4.4$ gpg --homedir ~/.gnupg-dm -K
1183      ~/.gnupg-dm/pubring.kbx
1184      ----------------------
1185      sec   rsa3072 2018-03-15 [SC] [expires: 2019-03-15]
1186            177B7C25DB99745EE2EE13ED026D2F19E99E63AA
1187      uid           [ultimate] Danger Mouse <dm@secret.example.net>
1188      ssb   rsa3072 2018-03-15 [E] [expires: 2018-09-13]
1189
1190      bash-4.4$
1191    #+end_src
1192
1193
1194 ** User IDs
1195    :PROPERTIES:
1196    :CUSTOM_ID: keygen-uids
1197    :END:
1198
1199    By comparison to creating primary keys and subkeys, adding a new
1200    user ID to an existing key is much simpler.  The method used to do
1201    this is =key_add_uid= and the only arguments it takes are for the
1202    =key= and the new =uid=.
1203
1204    #+begin_src python
1205      import gpg
1206
1207      c = gpg.Context()
1208      c.home_dir = "~/.gnupg-dm"
1209
1210      dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA"
1211      key = c.get_key(dmfpr, secret = True)
1212      uid = "Danger Mouse <danger.mouse@secret.example.net>"
1213
1214      c.key_add_uid(key, uid)
1215    #+end_src
1216
1217    Unsurprisingly the result of this is:
1218
1219    #+begin_src shell
1220      bash-4.4$ gpg --homedir ~/.gnupg-dm -K
1221      ~/.gnupg-dm/pubring.kbx
1222      ----------------------
1223      sec   rsa3072 2018-03-15 [SC] [expires: 2019-03-15]
1224            177B7C25DB99745EE2EE13ED026D2F19E99E63AA
1225      uid           [ultimate] Danger Mouse <danger.mouse@secret.example.net>
1226      uid           [ultimate] Danger Mouse <dm@secret.example.net>
1227      ssb   rsa3072 2018-03-15 [E] [expires: 2018-09-13]
1228
1229      bash-4.4$
1230    #+end_src
1231
1232
1233 ** Key certification
1234    :PROPERTIES:
1235    :CUSTOM_ID: key-sign
1236    :END:
1237
1238    Since key certification is more frequently referred to as key
1239    signing, the method used to perform this function is =key_sign=.
1240
1241    The =key_sign= method takes four arguments: =key=, =uids=,
1242    =expires_in= and =local=.  The default value of =uids= is =None=
1243    and which results in all user IDs being selected.  The default
1244    values of =expires_in= snd =local= is =False=; which result in the
1245    signature never expiring and being able to be exported.
1246
1247    The =key= is the key being signed rather than the key doing the
1248    signing.  To change the key doing the signing refer to the signing
1249    key selection above for signing messages and files.
1250
1251    If the =uids= value is not =None= then it must either be a string
1252    to match a single user ID or a list of strings to match multiple
1253    user IDs.  In this case the matching of those strings must be
1254    precise and it is case sensitive.
1255
1256    To sign Danger Mouse's key for just the initial user ID with a
1257    signature which will last a little over a month, do this:
1258
1259    #+begin_src python
1260      import gpg
1261
1262      c = gpg.Context()
1263      uid = "Danger Mouse <dm@secret.example.net>"
1264
1265      dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA"
1266      key = c.get_key(dmfpr, secret = True)
1267      c.key_sign(key, uids = uid, expires_in = 2764800)
1268    #+end_src
1269
1270
1271 * Miscellaneous work-arounds
1272   :PROPERTIES:
1273   :CUSTOM_ID: cheats-and-hacks
1274   :END:
1275
1276
1277 ** Group lines
1278    :PROPERTIES:
1279    :CUSTOM_ID: group-lines
1280    :END:
1281
1282    There is not yet an easy way to access groups configured in the
1283    gpg.conf file from within GPGME.  As a consequence these central
1284    groupings of keys cannot be shared amongst multiple programs, such
1285    as MUAs readily.
1286
1287    The following code, however, provides a work-around for obtaining
1288    this information in Python.
1289
1290    #+begin_src python
1291      import subprocess
1292
1293      lines = subprocess.getoutput("gpgconf --list-options gpg").splitlines()
1294
1295      for i in range(len(lines)):
1296          if lines[i].startswith("group") is True:
1297              line = lines[i]
1298          else:
1299              pass
1300
1301      groups = line.split(":")[-1].replace('"', '').split(',')
1302
1303      group_lines = groups
1304      for i in range(len(group_lines)):
1305          group_lines[i] = group_lines[i].split("=")
1306
1307      group_lists = group_lines
1308      for i in range(len(group_lists)):
1309          group_lists[i][1] = group_lists[i][1].split()
1310    #+end_src
1311
1312    The result of that code is that =group_lines= is a list of lists
1313    where =group_lines[i][0]= is the name of the group and
1314    =group_lines[i][1]= is the key IDs of the group as a string.
1315
1316    The =group_lists= result is very similar in that it is a list of
1317    lists.  The first part, =group_lists[i][0]= matches
1318    =group_lines[i][0]= as the name of the group, but
1319    =group_lists[i][1]= is the key IDs of the group as a string.
1320
1321
1322 * Copyright and Licensing
1323   :PROPERTIES:
1324   :CUSTOM_ID: copyright-and-license
1325   :END:
1326
1327
1328 ** Copyright (C) The GnuPG Project, 2018
1329    :PROPERTIES:
1330    :CUSTOM_ID: copyright
1331    :END:
1332
1333    Copyright © The GnuPG Project, 2018.
1334
1335
1336 ** License GPL compatible
1337    :PROPERTIES:
1338    :CUSTOM_ID: license
1339    :END:
1340
1341    This file is free software; as a special exception the author gives
1342    unlimited permission to copy and/or distribute it, with or without
1343    modifications, as long as this notice is preserved.
1344
1345    This file is distributed in the hope that it will be useful, but
1346    WITHOUT ANY WARRANTY, to the extent permitted by law; without even
1347    the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
1348    PURPOSE.
1349
1350
1351 * Footnotes
1352
1353 [fn:1] =Short_History.org= and/or =Short_History.html=.
1354
1355 [fn:2] The =lang/python/docs/= directory in the GPGME source.
1356
1357 [fn:3] You probably don't really want to do this.  Searching the
1358 keyservers for "gnupg.org" produces over 400 results, the majority of
1359 which aren't actually at the gnupg.org domain, but just included a
1360 comment regarding the project in their key somewhere.