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