python docs: checking key signatures

* Added instructions for checking key certifications or key
  signatures (depending on preferred terminology).
* Added pendulum module to recommended installations, but not to
  requirements.

Tested-by: Ben McGinnes <[email protected]>
Signed-off-by: Ben McGinnes <[email protected]>

1 files changed, 90 insertions, 8 deletions

diff --git a/lang/python/doc/texinfo/gpgme-python-howto.texi b/lang/python/doc/texinfo/gpgme-python-howto.texi
index 3ac26d69..558bc873 100644
--- a/lang/python/doc/texinfo/gpgme-python-howto.texi
+++ b/lang/python/doc/texinfo/gpgme-python-howto.texi
@@ -141,6 +141,10 @@ User IDs
 * Adding User IDs::
 * Revoking User IDs::
 
+Key certification
+
+* Verifying key certifications::
+
 Advanced or Experimental Use Cases
 
 * C plus Python plus SWIG plus Cython::
@@ -432,16 +436,17 @@ reach EOL soon.  In production systems and services, Python 3.6
 should be robust enough to be relied on.
 @item
 If possible add the following Python modules which are not part of
-the standard library: @uref{http://docs.python-requests.org/en/latest/index.html, Requests}, @uref{https://cython.org/, Cython} and @uref{https://github.com/Selfnet/hkp4py, hkp4py}.  Chances are
-quite high that at least the first one and maybe two of those will
-already be installed.
+the standard library: @uref{http://docs.python-requests.org/en/latest/index.html, Requests}, @uref{https://cython.org/, Cython}, @uref{https://pendulum.eustace.io/, Pendulum} and @uref{https://github.com/Selfnet/hkp4py, hkp4py}.
 @end enumerate
 
-Note that, as with Cython, some of the planned additions to the
-@ref{Advanced or Experimental Use Cases, , Advanced} section, will bring with them additional requirements.  Most
-of these will be fairly well known and commonly installed ones,
-however, which are in many cases likely to have already been installed
-on many systems or be familiar to Python programmers.
+Chances are quite high that at least the first one and maybe two of
+those will already be installed.
+
+Note that, as with Cython, some of advanced use case scenarios will
+bring with them additional requirements.  Most of these will be fairly
+well known and commonly installed ones, however, which are in many
+cases likely to have already been installed on many systems or be
+familiar to Python programmers.
 
 @node Installation
 @section Installation
@@ -2754,6 +2759,83 @@ key = c.get_key(dmfpr, secret=True)
 c.key_sign(key, uids=uid, expires_in=2764800)
 @end example
 
+@menu
+* Verifying key certifications::
+@end menu
+
+@node Verifying key certifications
+@subsection Verifying key certifications
+
+@example
+import gpg
+import time
+
+c = gpg.Context()
+dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA"
+keys = list(c.keylist(pattern=dmuid, mode=gpg.constants.keylist.mode.SIGS))
+key = keys[0]
+
+for user in key.uids:
+    for sig in user.signatures:
+        print("0x@{0@}".format(sig.keyid), "", time.ctime(sig.timestamp), "",
+              sig.uid)
+@end example
+
+Which for Danger Mouse displays the following:
+
+@example
+0x92E3F6115435C65A  Thu Mar 15 13:17:44 2018  Danger Mouse <dm@@secret.example.net>
+0x321E4E2373590E5D  Mon Nov 26 12:46:05 2018  Ben McGinnes <ben@@adversary.org>
+@end example
+
+The two key signatures listed are for the self-certification of Danger
+Mouse's key made when the key was created in March, 2018; and the
+second is a signature made by the author and set to expire at the end
+of the year.  Note that the second signature was made with the
+following code (including the preceding code to display the output of
+the certifications or key signatures):
+
+@example
+import gpg
+import math
+import pendulum
+import time
+
+hd = "/home/dm/.gnupg"
+c = gpg.Context()
+d = gpg.Context(home_dir=hd)
+dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA"
+dmuid = "Danger Mouse <dm@@secret.example.net>"
+dkeys = list(c.keylist(pattern=dmuid))
+dmkey = dkeys[0]
+
+c.key_import(d.key_export(pattern=None))
+
+tp = pendulum.period(pendulum.now(tz="local"), pendulum.datetime(2019, 1, 1))
+ts = tp.total_seconds()
+total_secs = math.ceil(ts)
+c.key_sign(dmkey, uids=dmuid, expires_in=total_secs)
+
+d.key_import(c.key_export(pattern=dmuid))
+keys = list(c.keylist(pattern=dmuid, mode=gpg.constants.keylist.mode.SIGS))
+key = keys[0]
+
+for user in key.uids:
+    for sig in user.signatures:
+        print("0x@{0@}".format(sig.keyid), "", time.ctime(sig.timestamp), "",
+              sig.uid)
+@end example
+
+Note that this final code block includes the use of a module which is
+@emph{not} part of Python's standard library, the @uref{https://pendulum.eustace.io/, pendulum module}.  Unlike
+the standard datetime module, pendulum makes working with dates and
+times significantly easier in Python; just as the requests module
+makes working with HTTP and HTTPS easier than the builtin modules do.
+
+Though neither requests nor pendulum are required modules for using
+the GPGME Python bindings, they are both highly recommended more
+generally.
+
 @node Advanced or Experimental Use Cases
 @chapter Advanced or Experimental Use Cases