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