doc: python bindings howto
[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.0.1-alpha                              |
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 ** Python 2 versus Python 3
26    :PROPERTIES:
27    :CUSTOM_ID: py2-vs-py3
28    :END:
29
30    Though the GPGME Python bindings themselves provide support for
31    both Python 2 and 3, the focus is unequivocally on Python 3 and
32    specifically from Python 3.4 and above.  As a consequence all the
33    examples and instructions in this guide use Python 3 code.
34
35    Much of it will work with Python 2, but much of it also deals with
36    Python 3 byte literals, particularly when reading and writing data.
37    Developers concentrating on Python 2.7, and possibly even 2.6, will
38    need to make the approprate modifications to support the older
39    string and unicode types as opposted to bytes.
40
41    There are multiple reasons for concentrating on Python 3; some of
42    which relate to the immediate integration of these bindings, some
43    of which relate to longer term plans for both GPGME and the python
44    bindings and some of which relate to the impending EOL period for
45    Python 2.7.  Essentially, though, there is little value in tying
46    the bindings to a version of the language which is a dead end and
47    the advantages offered by Python 3 over Python 2 make handling the
48    data types with which GPGME deals considerably easier.
49
50
51 * GPGME Concepts
52   :PROPERTIES:
53   :CUSTOM_ID: gpgme-concepts
54   :END:
55
56 ** A C API
57    :PROPERTIES:
58    :CUSTOM_ID: gpgme-c-api
59    :END:
60
61    Unlike many modern APIs with which programmers will be more
62    familiar with these days, the GPGME API is a C API.  The API is
63    intended for use by C coders who would be able to access its
64    features by including the =gpgme.h= header file eith their own C
65    source code and then access its functions just as they would any
66    other C headers.
67
68    This is a very effective method of gaining complete access to the
69    API and in the most efficient manner possible.  It does, however,
70    have the drawback that it cannot be directly used by other
71    languages without some means of providing an interface to those
72    languages.  This is where the need for bindings in various
73    languages stems.
74
75 ** Python bindings
76    :PROPERTIES:
77    :CUSTOM_ID: gpgme-python-bindings
78    :END:
79
80    The Python bindings for GPGME provide a higher level means of
81    accessing the complete feature set of GPGME itself.  It also
82    provides a more pythonic means of calling these API functions.
83
84    The bindings are generated dynamically with SWIG and the copy of
85    =gpgme.h= generated when GPGME is compiled.
86
87    This means that a version of the Python bindings is fundamentally
88    tied to the exact same version of GPGME used to generate that copy
89    of =gpgme.h=.
90
91 ** Difference between the Python bindings and other GnuPG Python packages
92    :PROPERTIES:
93    :CUSTOM_ID: gpgme-python-bindings-diffs
94    :END:
95
96    There have been numerous attempts to add GnuPG support to Python
97    over the years.  Some of the most well known are listed here, along
98    with what differentiates them.
99
100 *** The python-gnupg package maintained by Vinay Sajip
101     :PROPERTIES:
102     :CUSTOM_ID: diffs-python-gnupg
103     :END:
104
105     This is arguably the most popular means of integrating GPG with
106     Python.  The package utilises the =subprocess= module to implement
107     wrappers for the =gpg= and =gpg2= executables normally invoked on
108     the command line (=gpg.exe= and =gpg2.exe= on Windows).
109
110     The popularity of this package stemmed from its ease of use and
111     capability in providing the most commonly required features.
112
113     Unfortunately it has been beset by a number of security issues,
114     most of which stemmed from using unsafe methods of accessing the
115     command line via the =subprocess= calls.
116
117     The python-gnupg package is available under the MIT license.
118
119 *** The gnupg package created and maintained by Isis Lovecruft
120     :PROPERTIES:
121     :CUSTOM_ID: diffs-isis-gnupg
122     :END:
123
124     In 2015 Isis Lovecruft from the Tor Project forked and then
125     re-implemented the python-gnupg package as just gnupg.  This new
126     package also relied on subprocess to call the =gpg= or =gpg2=
127     binaries, but did so somewhat more securely.
128
129     However the naming and version numbering selected for this package
130     resulted in conflicts with the original python-gnupg and since its
131     functions were called in a different manner, the release of this
132     package also resulted in a great deal of consternation when people
133     installed what they thought was an upgrade that subsequently broke
134     the code relying on it.
135
136     The gnupg package is available under the GNU General Public
137     License version 3.0 (or later).
138
139 *** The PyME package maintained by Martin Albrecht
140     :PROPERTIES:
141     :CUSTOM_ID: diffs-pyme
142     :END:
143
144     This package is the origin of these bindings, though they are
145     somewhat different now.  For details of when and how the PyME
146     package was folded back into GPGME itself see the /Short History/
147     document[fn:1] in this Python bindings =docs= directory.[fn:2]
148
149     The PyME package was first released in 2002 and was also the first
150     attempt to implement a low level binding to GPGME.  In doing so it
151     provided access to considerably more functionality than either the
152     =python-gnupg= or =gnupg= packages.
153
154     The PyME package is only available for Python 2.6 and 2.7.
155
156     Porting the PyME package to Python 3.4 in 2015 is what resulted in
157     it being folded into the GPGME project and the current bindings
158     are the end result of that effort.
159
160     The PyME package is available under the same dual licensing as
161     GPGME itself: the GNU General Public License version 2.0 (or any
162     later version) and the GNU Lesser Public License version 2.1 (or
163     any later version).
164
165
166 * GPGME Python bindings installation
167   :PROPERTIES:
168   :CUSTOM_ID: gpgme-python-install
169   :END:
170
171 ** No PyPI
172    :PROPERTIES:
173    :CUSTOM_ID: do-not-use-pypi
174    :END:
175
176    Most third-party Python packages and modules are available and
177    distributed through the Python Package Installer, known as PyPI.
178
179    Due to the nature of what these bindings are and how they work, it
180    is infeasible to install the GPGME Python bindings in the same way.
181
182 ** Requirements
183    :PROPERTIES:
184    :CUSTOM_ID: gpgme-python-requirements
185    :END:
186
187    The GPGME Python bindings only have three requirements:
188
189    1. A suitable version of Python 2 or Python 3.  With Python 2 that
190       means Python 2.7 and with Python 3 that means Python 3.4 or
191       higher.
192    2. SWIG.
193    3. GPGME itself.  Which also means that all of GPGME's dependencies
194       must be installed too.
195
196 ** Installation
197    :PROPERTIES:
198    :CUSTOM_ID: installation
199    :END:
200
201    Installing the Python bindings is effectively achieved by compiling
202    and installing GPGME itself.
203
204    Once SWIG is installed with Python and all the dependencies for
205    GPGME are installed you only need to confirm that the version(s) of
206    Python you want the bindings installed for are in your =$PATH=.
207
208    By default GPGME will attempt to install the bindings for the most
209    recent or highest version number of Python 2 and Python 3 it
210    detects in =$PATH=.  It specifically checks for the =python= and
211    =python3= executabled first and then checks for specific version
212    numbers.
213
214    For Python 2 it checks for these executables in this order:
215    =python=, =python2= and =python2.7=.
216
217    For Python 3 it checks for these executables in this order:
218    =python3=, =python3.6=, =python3.5= and =python3.4=.
219
220 *** Installing GPGME
221     :PROPERTIES:
222     :CUSTOM_ID: install-gpgme
223     :END:
224
225     See the GPGME =README= file for details of how to install GPGME from
226     source.
227
228
229 * Fundamentals
230   :PROPERTIES:
231   :CUSTOM_ID: howto-fund-a-mental
232   :END:
233
234   Before we can get to the fun stuff, there are a few matters
235   regarding GPGME's design which hold true whether you're dealing with
236   the C code directly or these Python bindings.
237
238 ** No REST
239    :PROPERTIES:
240    :CUSTOM_ID: no-rest-for-the-wicked
241    :END:
242
243    The first part of which is or will be fairly blatantly obvious upon
244    viewing the first example, but it's worth reiterating anyway.  That
245    being that this API is /*not*/ a REST API.  Nor indeed could it
246    ever be one.
247
248    Most, if not all, Python programmers (and not just Python
249    programmers) know how easy it is to work with a RESTful API.  In
250    fact they've become so popular that many other APIs attempt to
251    emulate REST-like behaviour as much as they are able.  Right down
252    to the use of JSON formatted output to facilitate the use of their
253    API without having to retrain developers.
254
255    This API does not do that.  It would not be able to do that and
256    also provide access to the entire C API on which it's built.  It
257    does, however, provide a very pythonic interface on top of the
258    direct bindings and it's this pythonic layer with which this HOWTO
259    deals with.
260
261 ** Context
262    :PROPERTIES:
263    :CUSTOM_ID: howto-get-context
264    :END:
265
266    One of the reasons which prevents this API from being RESTful is
267    that most operations require more than one instruction to the API
268    to perform the task.  Sure, there are certain functions which can
269    be performed simultaneously, particularly if the result known or
270    strongly anticipated (e.g selecting and encrypting to a key known
271    to be in the public keybox).
272
273    There are many more, however, which cannot be manipulated so
274    readily: they must be performed in a specific sequence and the
275    result of one operation has a direct bearing on the outcome of
276    subsequent operations.  Not merely by generating an error either.
277
278    When dealing with this type of persistant state on the web, full of
279    both the RESTful and REST-like, it's most commonly referred to as a
280    session.  In GPGME, however, it is called a context and every
281    operation type has one.
282
283
284 * Working with keys
285   :PROPERTIES:
286   :CUSTOM_ID: howto-keys
287   :END:
288
289 ** Key selection
290    :PROPERTIES:
291    :CUSTOM_ID: howto-keys-selection
292    :END:
293
294    Selecting keys to encrypt to or to sign with will be a common
295    occurrence when working with GPGMe and the means available for
296    doing so are quite simple.
297
298    They do depend on utilising a Context; however once the data is
299    recorded in another variable, that Context does not need to be the
300    same one which subsequent operations are performed.
301
302    The easiest way to select a specific key is by searching for that
303    key's key ID or fingerprint, preferably the full fingerprint
304    without any spaces in it.  A long key ID will probably be okay, but
305    is not advised and short key IDs are already a problem with some
306    being generated to match specific patterns.  It does not matter
307    whether the pattern is upper or lower case.
308
309    So this is the best method:
310
311    #+begin_src python
312      import gpg
313
314      k = gpg.Context().keylist(pattern="258E88DCBD3CD44D8E7AB43F6ECB6AF0DEADBEEF")
315      keys = list(k)
316    #+end_src
317
318    This is passable and very likely to be common:
319
320    #+begin_src python
321      import gpg
322
323      k = gpg.Context().keylist(pattern="0x6ECB6AF0DEADBEEF")
324      keys = list(k)
325    #+end_src
326
327    And this is a really bad idea:
328
329    #+begin_src python
330      import gpg
331
332      k = gpg.Context().keylist(pattern="0xDEADBEEF")
333      keys = list(k)
334    #+end_src
335
336    Alternatively it may be that the intention is to create a list of
337    keys which all match a particular search string.  For instance all
338    the addresses at a particular domain, like this:
339
340    #+begin_src python
341      import gpg
342
343      ncsc = gpg.Context().keylist(pattern="ncsc.mil")
344      nsa = list(ncsc)
345    #+end_src
346
347
348 ** Counting keys
349    :PROPERTIES:
350    :CUSTOM_ID: howto-keys-counting
351    :END:
352
353    Counting the number of keys in your public keybox (=pubring.kbx=),
354    the format which has superceded the old keyring format
355    (=pubring.gpg= and =secring.gpg=), or the number of secret keys is
356    a very simple task.
357
358    #+begin_src python
359      import gpg
360
361      c = gpg.Context()
362      seckeys = c.keylist(pattern=None, secret=True)
363      pubkeys = c.keylist(pattern=None, secret=False)
364
365      seclist = list(seckeys)
366      secnum = len(seclist)
367
368      publist = list(pubkeys)
369      pubnum = len(publist)
370
371      print("""
372      Number of secret keys:  {0}
373      Number of public keys:  {1}
374      """.format(secnum, pubnum)
375    #+end_src
376
377
378 * Basic Functions
379   :PROPERTIES:
380   :CUSTOM_ID: howto-the-basics
381   :END:
382
383   The most frequently called features of any cryptographic library
384   will be the most fundamental tasks for enxryption software.  In this
385   section we will look at how to programmatically encrypt data,
386   decrypt it, sign it and verify signatures.
387
388 ** Encryption
389    :PROPERTIES:
390    :CUSTOM_ID: howto-basic-encryption
391    :END:
392
393    Encrypting is very straight forward.  In the first example below
394    the message, =text=, is encrypted to a single recipient's key.  In
395    the second example the message will be encrypted to multiple
396    recipients.
397
398 *** Encrypting to one key
399     :PROPERTIES:
400     :CUSTOM_ID: howto-basic-encryption-single
401     :END:
402
403    The text is then encapsulated in a GPGME Data object as =plain= and
404    the =cipher= object is created with another Data object.  Then we
405    create the Context as =c= and set it to use the ASCII armoured
406    OpenPGP format.  In later examples there will be alternative
407    methods of setting the OpenPGP output to be ASCII armoured.
408
409    Next we prepare a keylist object in our Context and follow it with
410    specifying the recipients as =r=.  Note that the configuration in
411    one's =gpg.conf= file is honoured, so if you have the options set
412    to encrypt to one key or to a default key, that will be included
413    with this operation.
414
415    This is followed by a quick check to be sure that the recipient is
416    actually selected and that the key is available.  Assuming it is,
417    the encryption can proceed, but if not a message will print stating
418    the key was not found.
419
420    The encryption operation is invoked within the Context with the
421    =c.op_encrypt= function, loading the recipien (=r=), the message
422    (=plain=) and the =cipher=.  The =cipher.seek= uses =os.SEEK_SET=
423    to set the data to the correct byte format for GPGME to use it.
424
425    At this point we no longer need the plaintext material, so we
426    delete both the =text= and the =plain= objects.  Then we write the
427    encrypted data out to a file, =secret_plans.txt.asc=.
428
429    #+begin_src python
430      import gpg
431      import os
432
433      rkey = "0x12345678DEADBEEF"
434      text = """
435      Some plain text to test with.  Obtained from any input source Python can read.
436
437      It makes no difference whether it is string or bytes, but the bindings always
438      produce byte output data.  Which is useful to know when writing out either the
439      encrypted or decrypted results.
440
441      """
442
443      plain = gpg.core.Data(text)
444      cipher = gpg.core.Data()
445      c = gpg.core.Context()
446      c.set_armor(1)
447
448      c.op_keylist_start(rkey, 0)
449      r = c.op_keylist_next()
450
451      if r == None:
452          print("""The key for user "{0}" was not found""".format(rkey))
453      else:
454          try:
455              c.op_encrypt([r], 1, plain, cipher)
456              cipher.seek(0, os.SEEK_SET)
457              del(text)
458              del(plain)
459              afile = open("secret_plans.txt.asc", "wb")
460              afile.write(cipher.read())
461              afile.close()
462          except gpg.errors.GPGMEError as ex:
463              print(ex.getstring())
464    #+end_src
465
466 *** Encrypting to multiple keys
467     :PROPERTIES:
468     :CUSTOM_ID: howto-basic-encryption-multiple
469     :END:
470
471     Encrypting to multiple keys, in addition to a default key or a key
472     configured to always encrypt to, is a little different and uses a
473     slightly different call to the =op_encrypt call= demonstrated in the
474     previous section.
475
476     The following example encrypts a message (=text=) to everyone with
477     an email address on the =gnupg.org= domain,[fn:3] but does /not/ encrypt
478     to a default key or other key which is configured to normally
479     encrypt to.
480
481     #+begin_src python
482       import gpg
483
484       text = b"""Oh look, another test message.
485
486       The same rules apply as with the previous example and more likely
487       than not, the message will actually be drawn from reading the
488       contents of a file or, maybe, from entering data at an input()
489       prompt.
490
491       Since the text in this case must be bytes, it is most likely that
492       the input form will be a separate file which is opened with "rb"
493       as this is the simplest method of obtaining the correct data
494       format.
495       """
496
497       c = gpg.Context(armor=True)
498       rpattern = list(c.keylist(pattern="@gnupg.org", secret=False))
499       logrus = []
500
501       for i in range(len(rpattern)):
502           if rpattern[i].can_encrypt == 1:
503               logrus.append(rpattern[i])
504
505       cipher = c.encrypt(text, recipients=logrus, sign=False, always_trust=True)
506
507       afile = open("secret_plans.txt.asc", "wb")
508       afile.write(cipher[0])
509       afile.close()
510     #+end_src
511
512     All it would take to change the above example to sign the message
513     and also encrypt the message to any configured default keys would
514     be to change the =c.encrypt= line to this:
515
516     #+begin_src python
517       cipher = c.encrypt(text, recipients=logrus, always_trust=True,
518                          add_encrypt_to=True)
519     #+end_src
520
521     The only keyword arguments requiring modification are those for
522     which the default values are changing.  The default value of
523     =sign= is =True=, the default of =always_trust= is =False=, the
524     default of =add_encrypt_to= is =False=.
525
526     If =always_trust= is not set to =True= and any of the recipient
527     keys are not trusted (e.g. not signed or locally signed) then the
528     encryption will raise an error.  It is possible to mitigate this
529     somewhat with something more like this:
530
531     #+begin_src python
532       import gpg
533
534       afile = open("secret_plans.txt", "rb")
535       text = afile.read()
536       afile.close()
537
538       c = gpg.Context(armor=True)
539       rpattern = list(c.keylist(pattern="@gnupg.org", secret=False))
540       logrus = []
541
542       for i in range(len(rpattern)):
543           if rpattern[i].can_encrypt == 1:
544               logrus.append(rpattern[i])
545
546       try:
547           cipher = c.encrypt(text, recipients=logrus, add_encrypt_to=True)
548       except gpg.errors.InvalidRecipients as e:
549           for i in range(len(e.recipients)):
550               for n in range(len(logrus)):
551                   if logrus[n].fpr == e.recipients[i].fpr:
552                       logrus.remove(logrus[n])
553                   else:
554                       pass
555           try:
556               cipher = c.encrypt(text, recipients=logrus, add_encrypt_to=True)
557           except:
558               pass
559
560       afile = open("secret_plans.txt.asc", "wb")
561       afile.write(cipher[0])
562       afile.close()
563     #+end_src
564
565     This will attempt to encrypt to all the keys searched for, then
566     remove invalid recipients if it fails and try again.
567
568 **** Encrypting to one key using the second method
569      :PROPERTIES:
570      :CUSTOM_ID: howto-basic-encryption-monogamous
571      :END:
572
573      This example re-creates the first encryption example except it
574      uses the same =encrypt= method used in the subsequent examples
575      instead of the =op_encrypt= method.  This means that, unlike the
576      =op_encrypt= method, it /must/ use byte literal input data.
577
578      #+begin_src python
579        import gpg
580
581        rkey = "0x12345678DEADBEEF"
582        text = b"""Some text to test with.
583
584        Since the text in this case must be bytes, it is most likely that
585        the input form will be a separate file which is opened with "rb"
586        as this is the simplest method of obtaining the correct data
587        format.
588        """
589
590        c = gpg.Context(armor=True)
591        rpattern = list(c.keylist(pattern=rkey, secret=False))
592        logrus = []
593
594        for i in range(len(rpattern)):
595            if rpattern[i].can_encrypt == 1:
596                logrus.append(rpattern[i])
597
598        cipher = c.encrypt(text, recipients=logrus, sign=False, always_trust=True)
599
600        afile = open("secret_plans.txt.asc", "wb")
601        afile.write(cipher[0])
602        afile.close()
603      #+end_src
604
605      With one or two exceptions, this method will probably prove to be
606      easier to implement than the first method and thus it is the
607      recommended encryption method.  Though it is even more likely to
608      be used like this:
609
610      #+begin_src python
611        import gpg
612
613        rkey = "0x12345678DEADBEEF"
614
615        afile = open("secret_plans.txt", "rb")
616        text = afile.read()
617        afile.close()
618
619        c = gpg.Context(armor=True)
620        rpattern = list(c.keylist(pattern=rkey, secret=False))
621        logrus = []
622
623        for i in range(len(rpattern)):
624            if rpattern[i].can_encrypt == 1:
625                logrus.append(rpattern[i])
626
627        cipher = c.encrypt(text, recipients=logrus, sign=False, always_trust=True)
628
629        afile = open("secret_plans.txt.asc", "wb")
630        afile.write(cipher[0])
631        afile.close()
632      #+end_src
633
634
635 ** Decryption
636    :PROPERTIES:
637    :CUSTOM_ID: howto-basic-encryption
638    :END:
639
640    Decrypting something encrypted to a key in one's secret keyring is
641    fairly straight forward.
642
643    In this example code, however, preconfiguring either
644    =gpg.Context()= or =gpg.core.Context()= as =c= is unnecessary
645    because there is no need to modify the Context prior to conducting
646    the decryption and since the Context is only used once, setting it
647    to =c= simply adds lines for no gain.
648
649    #+begin_src python
650      import os.path
651      import gpg
652
653      if os.path.exists("/path/to/secret_plans.txt.asc") is True:
654          ciphertext = "/path/to/secret_plans.txt.asc"
655      elif os.path.exists("/path/to/secret_plans.txt.gpg") is True:
656          ciphertext = "/path/to/secret_plans.txt.gpg"
657      else:
658          ciphertext = None
659
660      if ciphertext is not None:
661          afile = open(ciphertext, "rb")
662          plaintext = gpg.Context().decrypt(afile)
663          afile.close()
664          newfile = open("/path/to/secret_plans.txt", "wb")
665          newfile.write(plaintext[0])
666          newfile.close()
667          print(plaintext[0])
668          plaintext[1]
669          plaintext[2]
670          del(plaintext)
671      else:
672          pass
673    #+end_src
674
675    The data available in plaintext in this example is the decrypted
676    content as a byte object in =plaintext[0]=, the recipient key IDs
677    and algorithms in =plaintext[1]= and the results of verifying any
678    signatures of the data in =plaintext[0]=.
679
680
681 ** Signing text and files
682    :PROPERTIES:
683    :CUSTOM_ID: howto-basic-signing
684    :END:
685
686    The following sections demonstrate how to specify
687
688 *** Signing key selection
689     :PROPERTIES:
690     :CUSTOM_ID: howto-basic-signing-signers
691     :END:
692
693     By default GPGME and the Python bindings will use the default key
694     configured for the user invoking the GPGME API.  If there is no
695     default key specified and there is more than one secret key
696     available it may be necessary to specify the key or keys with
697     which to sign messages and files.
698
699     #+begin_src python
700       import gpg
701
702       logrus = input("Enter the email address or string to match signing keys to: ")
703       hancock = gpg.Context().keylist(pattern=logrus, secret=True)
704       sig_src = list(hancock)
705     #+end_src
706
707     The signing examples in the following sections include the
708     explicitly designated =signers= parameter in two of the five
709     examples; once where the resulting signature would be ASCII
710     armoured and once where it would not be armoured.
711
712     While it would be possible to enter a key ID or fingerprint here
713     to match a specific key, it is not possible to enter two
714     fingerprints and match two keys since the patten expects a string,
715     bytes or None and not a list.  A string with two fingerprints
716     won't match any single key.
717
718 *** Normal or default signing messages or files
719     :PROPERTIES:
720     :CUSTOM_ID: howto-basic-signing-normal
721     :END:
722
723     The normal or default signing process is essentially the same as
724     is most often invoked when also encrypting a message or file.  So
725     when the encryption component is not utilised, the result is to
726     produce an encoded and signed output which may or may not be ASCII
727     armoured and which may or may not also be compressed.
728
729     By default compression will be used unless GnuPG detects that the
730     plaintext is already compressed.  ASCII armouring will be
731     determined according to the value of =gpg.Context().armor=.
732
733     The compression algorithm is selected in much the same way as the
734     symmetric encryption algorithm or the hash digest algorithm is
735     when multiple keys are involved; from the preferences saved into
736     the key itself or by comparison with the preferences with all
737     other keys involved.
738
739    #+begin_src python
740      import gpg
741
742      text0 = """Declaration of ... something.
743
744      """
745      text = text0.encode("utf-8")
746
747      c = gpg.Context(armor=True, signers=sig_src)
748      signed = c.sign(text, mode=0)
749
750      afile = open("/path/to/statement.txt.asc", "w")
751      for line in signed[0]:
752          afile.write("{0}\n".format(line.decode("utf-8")))
753      afile.close()
754    #+end_src
755
756    Though everything in this example is accurate, it is more likely
757    that reading the input data from another file and writing the
758    result to a new file will be perfprmed more like the way it is done
759    in the next example.  Even if the output format is ASCII armoured.
760
761    #+begin_src python
762      import gpg
763
764      tfile = open("/path/to/statement.txt", "rb")
765      text = tfile.read()
766      tfile.close()
767
768      c = gpg.Context()
769      signed = c.sign(text, mode=0)
770
771      afile = open("/path/to/statement.txt.sig", "wb")
772      afile.write(signed[0])
773      afile.close()
774    #+end_src
775
776 *** Detached signing messages and files
777     :PROPERTIES:
778     :CUSTOM_ID: howto-basic-signing-detached
779     :END:
780
781     Detached signatures will often be needed in programmatic uses of
782     GPGME, either for signing files (e.g. tarballs of code releases)
783     or as a component of message signing (e.g. PGP/MIME encoded
784     email).
785
786     #+begin_src python
787       import gpg
788
789       text0 = """Declaration of ... something.
790
791       """
792       text = text0.encode("utf-8")
793
794       c = gpg.Context(armor=True)
795       signed = c.sign(text, mode=1)
796
797       afile = open("/path/to/statement.txt.asc", "w")
798       for line in signed[0].splitlines()L
799           afile.write("{0}\n".format(line.decode("utf-8")))
800       afile.close()
801     #+end_src
802
803     As with normal signatures, detached signatures are best handled as
804     byte literals, even when the output is ASCII armoured.
805
806     #+begin_src python
807       import gpg
808
809       tfile = open("/path/to/statement.txt", "rb")
810       text = tfile.read()
811       tfile.close()
812
813       c = gpg.Context(signers=sig_src)
814       signed = c.sign(text, mode=1)
815
816       afile = open("/path/to/statement.txt.sig", "wb")
817       afile.write(signed[0])
818       afile.close()
819     #+end_src
820
821 *** Clearsigning messages or text
822     :PROPERTIES:
823     :CUSTOM_ID: howto-basic-signing-clear
824     :END:
825
826     Though PGP/in-line messages are no longer encouraged in favour of
827     PGP/MIME, there is still sometimes value in utilising in-line
828     signatures.  This is where clear-signed messages or text is of
829     value.
830
831     #+begin_src python
832       import gpg
833
834       text0 = """Declaration of ... something.
835
836       """
837       text = text0.encode("utf-8")
838
839       c = gpg.Context()
840       signed = c.sign(text, mode=2)
841
842       afile = open("/path/to/statement.txt.asc", "w")
843       for line in signed[0].splitlines():
844           afile.write("{0}\n".format(line.decode("utf-8")))
845       afile.close()
846     #+end_src
847
848     In spite of the appearance of a clear-signed message, the data
849     handled by GPGME in signing it must still be byte literals.
850
851     #+begin_src python
852       import gpg
853
854       tfile = open("/path/to/statement.txt", "rb")
855       text = tfile.read()
856       tfile.close()
857
858       c = gpg.Context()
859       signed = c.sign(text, mode=2)
860
861       afile = open("/path/to/statement.txt.asc", "wb")
862       afile.write(signed[0])
863       afile.close()
864     #+end_src
865
866
867 ** Signature verification
868    :PROPERTIES:
869    :CUSTOM_ID: howto-basic-verification
870    :END:
871
872    Essentially there are two principal methods of verification of a
873    signature.  The first of these is for use with the normal or
874    default signing method and for clear-signed messages.  The second is
875    for use with files and data with detached signatures.
876
877    The following example is intended for use with the default signing
878    method where the file was not ASCII armoured:
879
880    #+begin_src python
881      import gpg
882      import time
883
884      filename = "statement.txt"
885      gpg_file = "statement.txt.gpg"
886
887      c = gpg.Context()
888
889      try:
890          verified = c.verify(open(gpg_file))
891      except gpg.errors.BadSignatures as e:
892          verified = None
893          print(e)
894
895      if verified is not None:
896          for i in range(len(verified[1].signatures)):
897              sign = verified[1].signatures[i]
898              print("""Good signature from:
899      {0}
900      with key {1}
901      made at {2}
902      """.format(c.get_key(sign.fpr).uids[0].uid,
903                 sign.fpr, time.ctime(sign.timestamp)))
904      else:
905          pass(e)
906    #+end_src
907
908    Whereas this next example, which is almost identical would work
909    with normal ASCII armoured files and with clear-signed files:
910
911    #+begin_src python
912      import gpg
913      import time
914
915      filename = "statement.txt"
916      asc_file = "statement.txt.asc"
917
918      c = gpg.Context()
919
920      try:
921          verified = c.verify(open(asc_file))
922      except gpg.errors.BadSignatures as e:
923          verified = None
924          print(e)
925
926      if verified is not None:
927          for i in range(len(verified[1].signatures)):
928              sign = verified[1].signatures[i]
929              print("""Good signature from:
930      {0}
931      with key {1}
932      made at {2}
933      """.format(c.get_key(sign.fpr).uids[0].uid,
934                 sign.fpr, time.ctime(sign.timestamp)))
935      else:
936          pass
937    #+end_src
938
939    #+begin_src python
940      import gpg
941      import time
942
943      filename = "statement.txt"
944      sig_file = "statement.txt.sig"
945
946      c = gpg.Context()
947
948      try:
949          verified = c.verify(open(filename), open(sig_file))
950      except gpg.errors.BadSignatures as e:
951          verified = None
952          print(e)
953
954      if verified is not None:
955          for i in range(len(verified[1].signatures)):
956              sign = verified[1].signatures[i]
957              print("""Good signature from:
958      {0}
959      with key {1}
960      made at {2}
961      """.format(c.get_key(sign.fpr).uids[0].uid,
962                 sign.fpr, time.ctime(sign.timestamp)))
963      else:
964          pass
965    #+end_src
966
967    #+begin_src python
968      import gpg
969      import time
970
971      filename = "statement.txt"
972      asc_file = "statement.txt.asc"
973
974      c = gpg.Context()
975
976      try:
977          verified = c.verify(open(filename), open(asc_file))
978      except gpg.errors.BadSignatures as e:
979          verified = None
980          print(e)
981
982      if verified is not None:
983          for i in range(len(verified[1].signatures)):
984              sign = verified[1].signatures[i]
985              print("""Good signature from:
986      {0}
987      with key {1}
988      made at {2}
989      """.format(c.get_key(sign.fpr).uids[0].uid,
990                 sign.fpr, time.ctime(sign.timestamp)))
991      else:
992          pass
993    #+end_src
994
995
996 * Miscellaneous work-arounds
997   :PROPERTIES:
998   :CUSTOM_ID: cheats-and-hacks
999   :END:
1000
1001 ** Group lines
1002    :PROPERTIES:
1003    :CUSTOM_ID: group-lines
1004    :END:
1005
1006    There is not yet an easy way to access groups configured in the
1007    gpg.conf file from within GPGME.  As a consequence these central
1008    groupings of keys cannot be shared amongst multiple programs, such
1009    as MUAs readily.
1010
1011    The following code, however, provides a work-around for obtaining
1012    this information in Python.
1013
1014    #+begin_src python
1015      import subprocess
1016
1017      lines = subprocess.getoutput("gpgconf --list-options gpg").splitlines()
1018
1019      for i in range(len(lines)):
1020          if lines[i].startswith("group") is True:
1021              line = lines[i]
1022          else:
1023              pass
1024
1025      groups = line.split(":")[-1].replace('"', '').split(',')
1026
1027      group_lines = groups
1028      for i in range(len(group_lines)):
1029          group_lines[i] = group_lines[i].split("=")
1030
1031      group_lists = group_lines
1032      for i in range(len(group_lists)):
1033          group_lists[i][1] = group_lists[i][1].split()
1034    #+end_src
1035
1036    The result of that code is that =group_lines= is a list of lists
1037    where =group_lines[i][0]= is the name of the group and
1038    =group_lines[i][1]= is the key IDs of the group as a string.
1039
1040    The =group_lists= result is very similar in that it is a list of
1041    lists.  The first part, =group_lists[i][0]= matches
1042    =group_lines[i][0]= as the name of the group, but
1043    =group_lists[i][1]= is the key IDs of the group as a string.
1044
1045
1046 * Copyright and Licensing
1047   :PROPERTIES:
1048   :CUSTOM_ID: copyright-and-license
1049   :END:
1050
1051 ** Copyright (C) The GnuPG Project, 2018
1052    :PROPERTIES:
1053    :CUSTOM_ID: copyright
1054    :END:
1055
1056    Copyright © The GnuPG Project, 2018.
1057
1058 ** License GPL compatible
1059    :PROPERTIES:
1060    :CUSTOM_ID: license
1061    :END:
1062
1063    This file is free software; as a special exception the author gives
1064    unlimited permission to copy and/or distribute it, with or without
1065    modifications, as long as this notice is preserved.
1066
1067    This file is distributed in the hope that it will be useful, but
1068    WITHOUT ANY WARRANTY, to the extent permitted by law; without even
1069    the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
1070    PURPOSE.
1071
1072
1073 * Footnotes
1074
1075 [fn:1] =Short_History.org= and/or =Short_History.html=.
1076
1077 [fn:2] The =lang/python/docs/= directory in the GPGME source.
1078
1079 [fn:3] You probably don't really want to do this.  Searching the
1080 keyservers for "gnupg.org" produces over 400 results, the majority of
1081 which aren't actually at the gnupg.org domain, but just included a
1082 comment regarding the project in their key somewhere.