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