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