Merge branch 'ben/howto-update-02' of ssh+git://playfair.gnupg.org/git/gpgme

6 files changed, 370 insertions, 49 deletions

diff --git a/lang/python/docs/GPGMEpythonHOWTOen.org b/lang/python/docs/GPGMEpythonHOWTOen.org
index 08f9ef75..d51eb11b 100644
--- a/lang/python/docs/GPGMEpythonHOWTOen.org
+++ b/lang/python/docs/GPGMEpythonHOWTOen.org
@@ -6,6 +6,7 @@
 #+LATEX_HEADER: \usepackage[margin=1in]{geometry}
 #+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Times New Roman}
 #+LATEX_HEADER: \author{Ben McGinnes <[email protected]>}
+#+HTML_HEAD_EXTRA: <link type="application/rss+xml" href="https://git.gnupg.org/cgi-bin/gitweb.cgi?p=gpgme.git;a=rss;f=lang/python/docs/GPGMEpythonHOWTOen.org"/>
 
 
 * Introduction
@@ -164,7 +165,7 @@
     This package is the origin of these bindings, though they are
     somewhat different now.  For details of when and how the PyME
     package was folded back into GPGME itself see the /Short History/
-    document[fn:1] in this Python bindings =docs= directory.[fn:2]
+    document[fn:1] in the Python bindings =docs= directory.[fn:2]
 
     The PyME package was first released in 2002 and was also the first
     attempt to implement a low level binding to GPGME.  In doing so it
@@ -536,8 +537,7 @@
       c = gpg.Context(armor=True)
       rkey = list(c.keylist(pattern=a_key, secret=False))
       ciphertext, result, sign_result = c.encrypt(text, recipients=rkey,
-						  sign=True, always_trust=True,
-                                                  add_encrypt_to=True)
+			      sign=True, always_trust=True, add_encrypt_to=True)
 
       with open("secret_plans.txt.asc", "wb") as afile:
 	  afile.write(ciphertext)
@@ -588,10 +588,10 @@
 	      logrus.append(rpattern[i])
 
       ciphertext, result, sign_result = c.encrypt(text, recipients=logrus, sign=False,
-                                                  always_trust=True)
+						  always_trust=True)
 
       with open("secret_plans.txt.asc", "wb") as afile:
-          afile.write(ciphertext)
+	  afile.write(ciphertext)
     #+end_src
 
     All it would take to change the above example to sign the message
@@ -600,7 +600,7 @@
 
     #+begin_src python
       ciphertext, result, sign_result = c.encrypt(text, recipients=logrus,
-			                          always_trust=True,
+						  always_trust=True,
 						  add_encrypt_to=True)
     #+end_src
 
@@ -618,7 +618,7 @@
       import gpg
 
       with open("secret_plans.txt.asc", "rb") as afile:
-          text = afile.read()
+	  text = afile.read()
 
       c = gpg.Context(armor=True)
       rpattern = list(c.keylist(pattern="@gnupg.org", secret=False))
@@ -629,21 +629,23 @@
 	      logrus.append(rpattern[i])
 
       try:
-	  ciphertext, result, sign_result = c.encrypt(text, recipients=logrus, add_encrypt_to=True)
+	  ciphertext, result, sign_result = c.encrypt(text, recipients=logrus,
+						      add_encrypt_to=True)
       except gpg.errors.InvalidRecipients as e:
 	  for i in range(len(e.recipients)):
 	      for n in range(len(logrus)):
 		  if logrus[n].fpr == e.recipients[i].fpr:
 		      logrus.remove(logrus[n])
-                  else:
-                      pass
+		  else:
+		      pass
 	  try:
-	      ciphertext, result, sign_result = c.encrypt(text, recipients=logrus, add_encrypt_to=True)
+	      ciphertext, result, sign_result = c.encrypt(text, recipients=logrus,
+							  add_encrypt_to=True)
 	  except:
 	      pass
 
       with open("secret_plans.txt.asc", "wb") as afile:
-          afile.write(ciphertext)
+	  afile.write(ciphertext)
     #+end_src
 
     This will attempt to encrypt to all the keys searched for, then
@@ -669,10 +671,12 @@
 
      ciphertext = input("Enter path and filename of encrypted file: ")
      newfile = input("Enter path and filename of file to save decrypted data to: ")
+
      with open(ciphertext, "rb") as cfile:
-         plaintext, result, verify_result = gpg.Context().decrypt(cfile)
+	 plaintext, result, verify_result = gpg.Context().decrypt(cfile)
+
      with open(newfile, "wb") as nfile:
-         nfile.write(plaintext)
+	 nfile.write(plaintext)
    #+end_src
 
    The data available in =plaintext= in this example is the decrypted
@@ -1078,8 +1082,8 @@
      c.home_dir = "~/.gnupg-dm"
      userid = "Danger Mouse <[email protected]>"
 
-     dmkey = c.create_key(userid, algorithm = "rsa3072", expires_in = 31536000,
-			  sign = True, certify = True)
+     dmkey = c.create_key(userid, algorithm="rsa3072", expires_in=31536000,
+			  sign=True, certify=True)
    #+end_src
 
    One thing to note here is the use of setting the =c.home_dir=
@@ -1171,9 +1175,9 @@
      c = gpg.Context()
      c.home_dir = "~/.gnupg-dm"
 
-     key = c.get_key(dmkey.fpr, secret = True)
-     dmsub = c.create_subkey(key, algorithm = "rsa3072", expires_in = 15768000,
-			     encrypt = True)
+     key = c.get_key(dmkey.fpr, secret=True)
+     dmsub = c.create_subkey(key, algorithm="rsa3072", expires_in=15768000,
+			     encrypt=True)
    #+end_src
 
    As with the primary key, the results here can be checked with:
@@ -1210,38 +1214,66 @@
    :CUSTOM_ID: keygen-uids
    :END:
 
-   By comparison to creating primary keys and subkeys, adding a new
-   user ID to an existing key is much simpler.  The method used to do
-   this is =key_add_uid= and the only arguments it takes are for the
-   =key= and the new =uid=.
 
-   #+begin_src python
-     import gpg
+*** Adding User IDs
+    :PROPERTIES:
+    :CUSTOM_ID: keygen-uids-add
+    :END:
 
-     c = gpg.Context()
-     c.home_dir = "~/.gnupg-dm"
+    By comparison to creating primary keys and subkeys, adding a new
+    user ID to an existing key is much simpler.  The method used to do
+    this is =key_add_uid= and the only arguments it takes are for the
+    =key= and the new =uid=.
 
-     dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA"
-     key = c.get_key(dmfpr, secret = True)
-     uid = "Danger Mouse <[email protected]>"
+    #+begin_src python
+      import gpg
 
-     c.key_add_uid(key, uid)
-   #+end_src
+      c = gpg.Context()
+      c.home_dir = "~/.gnupg-dm"
 
-   Unsurprisingly the result of this is:
+      dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA"
+      key = c.get_key(dmfpr, secret=True)
+      uid = "Danger Mouse <[email protected]>"
 
-   #+begin_src shell
-     bash-4.4$ gpg --homedir ~/.gnupg-dm -K
-     ~/.gnupg-dm/pubring.kbx
-     ----------------------
-     sec   rsa3072 2018-03-15 [SC] [expires: 2019-03-15]
-	   177B7C25DB99745EE2EE13ED026D2F19E99E63AA
-     uid           [ultimate] Danger Mouse <[email protected]>
-     uid           [ultimate] Danger Mouse <[email protected]>
-     ssb   rsa3072 2018-03-15 [E] [expires: 2018-09-13]
+      c.key_add_uid(key, uid)
+    #+end_src
 
-     bash-4.4$
-   #+end_src
+    Unsurprisingly the result of this is:
+
+    #+begin_src shell
+      bash-4.4$ gpg --homedir ~/.gnupg-dm -K
+      ~/.gnupg-dm/pubring.kbx
+      ----------------------
+      sec   rsa3072 2018-03-15 [SC] [expires: 2019-03-15]
+	    177B7C25DB99745EE2EE13ED026D2F19E99E63AA
+      uid           [ultimate] Danger Mouse <[email protected]>
+      uid           [ultimate] Danger Mouse <[email protected]>
+      ssb   rsa3072 2018-03-15 [E] [expires: 2018-09-13]
+
+      bash-4.4$
+    #+end_src
+
+
+*** Revokinging User IDs
+    :PROPERTIES:
+    :CUSTOM_ID: keygen-uids-revoke
+    :END:
+
+    Revoking a user ID is a fairly similar process, except that it
+    uses the =key_revoke_uid= method.
+
+    #+begin_src python
+      import gpg
+
+      c = gpg.Context()
+      c.home_dir = "~/.gnupg-dm"
+
+      dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA"
+      key = c.get_key(dmfpr, secret=True)
+      uid = "Danger Mouse <[email protected]>"
+
+      c.key_revoke_uid(key, uid)
+    #+end_src
 
 
 ** Key certification
@@ -1255,7 +1287,7 @@
    The =key_sign= method takes four arguments: =key=, =uids=,
    =expires_in= and =local=.  The default value of =uids= is =None=
    and which results in all user IDs being selected.  The default
-   values of =expires_in= snd =local= is =False=; which result in the
+   values of =expires_in= and =local= is =False=; which result in the
    signature never expiring and being able to be exported.
 
    The =key= is the key being signed rather than the key doing the
@@ -1277,8 +1309,8 @@
      uid = "Danger Mouse <[email protected]>"
 
      dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA"
-     key = c.get_key(dmfpr, secret = True)
-     c.key_sign(key, uids = uid, expires_in = 2764800)
+     key = c.get_key(dmfpr, secret=True)
+     c.key_sign(key, uids=uid, expires_in=2764800)
    #+end_src
 
 
diff --git a/lang/python/examples/howto/add-userid.py b/lang/python/examples/howto/add-userid.py
new file mode 100755
index 00000000..b8689792
--- /dev/null
+++ b/lang/python/examples/howto/add-userid.py
@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from __future__ import absolute_import, division, unicode_literals
+
+# Copyright (C) 2018 Ben McGinnes <[email protected]>
+#
+# This program is free software; you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 2 of the License, or (at your option) any later
+# version.
+#
+# This program is free software; you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation; either version 2.1 of the License, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU General Public License and the GNU
+# Lesser General Public Licensefor more details.
+#
+# You should have received a copy of the GNU General Public License and the GNU
+# Lesser General Public along with this program; if not, see
+# <http://www.gnu.org/licenses/>.
+
+import gpg
+import os.path
+
+print("""
+This script adds a new user ID to an existing key.
+
+The gpg-agent and pinentry are invoked to enter the passphrase.
+""")
+
+c = gpg.Context()
+
+homedir = input("Enter the GPG configuration directory path (optional): ")
+fpr0 = input("Enter the fingerprint of the key to modify: ")
+uid_name = input("Enter the name of the user ID: ")
+uid_email = input("Enter the email address of the user ID: ")
+uid_cmnt = input("Enter a comment to include (optional): ")
+
+if homedir.startswith("~"):
+    if os.path.exists(os.path.expanduser(homedir)) is True:
+        c.home_dir = os.path.expanduser(homedir)
+    else:
+        pass
+elif os.path.exists(homedir) is True:
+    c.home_dir = homedir
+else:
+    pass
+
+fpr = "".join(fpr0.split())
+
+if len(uid_cmnt) > 0:
+    userid = "{0} ({1}) <{2}>".format(uid_name, uid_cmnt, uid_email)
+else:
+    userid = "{0} <{2}>".format(uid_name, uid_email)
+
+key = c.get_key(fpr, secret=True)
+c.key_add_uid(key, userid)
diff --git a/lang/python/examples/howto/create-key.py b/lang/python/examples/howto/create-key.py
new file mode 100755
index 00000000..429ab1f7
--- /dev/null
+++ b/lang/python/examples/howto/create-key.py
@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from __future__ import absolute_import, division, unicode_literals
+
+# Copyright (C) 2018 Ben McGinnes <[email protected]>
+#
+# This program is free software; you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 2 of the License, or (at your option) any later
+# version.
+#
+# This program is free software; you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation; either version 2.1 of the License, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU General Public License and the GNU
+# Lesser General Public Licensefor more details.
+#
+# You should have received a copy of the GNU General Public License and the GNU
+# Lesser General Public along with this program; if not, see
+# <http://www.gnu.org/licenses/>.
+
+import gpg
+import os.path
+
+print("""
+This script generates a new key which does not expire.
+
+The gpg-agent and pinentry are invoked to set the passphrase.
+""")
+
+c = gpg.Context()
+
+homedir = input("Enter the GPG configuration directory path (optional): ")
+uid_name = input("Enter the name of the user ID: ")
+uid_email = input("Enter the email address of the user ID: ")
+uid_cmnt = input("Enter a comment to include (optional): ")
+key_algo = input("Enter the key algorithm, RSA or DSA (default is RSA): ")
+key_size = input("Enter the key size (2048-4096, default is 2048): ")
+
+if homedir.startswith("~"):
+    if os.path.exists(os.path.expanduser(homedir)) is True:
+        c.home_dir = os.path.expanduser(homedir)
+    else:
+        pass
+elif os.path.exists(homedir) is True:
+    c.home_dir = homedir
+else:
+    pass
+
+if len(uid_cmnt) > 0:
+    userid = "{0} ({1}) <{2}>".format(uid_name, uid_cmnt, uid_email)
+else:
+    userid = "{0} <{2}>".format(uid_name, uid_email)
+
+if key_algo.lower() == "dsa":
+    ka = "dsa"
+else:
+    ka = "rsa"
+
+if len(key_size) == 4:
+    try:
+        ks0 = int(key_size)
+    except ValueError:
+        ks0 = None
+    if ks0 is None:
+        ks = "2048"
+    else:
+        if ks0 < 2048:
+            ks = "2048"
+        elif ka == "dsa" and ks0 > 3072:
+            ks = "3072"
+        elif ka == "rsa" and ks0 > 4096:
+            ks = "4096"
+        else:
+            ks = key_size
+else:
+    ks = "2048"
+
+keyalgo = "{0}{1}".format(ka, ks)
+
+newkey = c.create_key(userid, algorithm=keyalgo, expires=False,
+                      passphrase=True, certify=True)
+key = c.get_key(newkey.fpr, secret=True)
+
+if ka == "rsa":
+    newsub = c.create_subkey(key, algorithm=keyalgo, expires=False,
+                             passphrase=True, encrypt=True)
+else:
+    newsub = c.create_subkey(key, expires=False, passphrase=True,
+                             encrypt=True)
diff --git a/lang/python/examples/howto/revoke-userid.py b/lang/python/examples/howto/revoke-userid.py
new file mode 100755
index 00000000..7a3d190b
--- /dev/null
+++ b/lang/python/examples/howto/revoke-userid.py
@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from __future__ import absolute_import, division, unicode_literals
+
+# Copyright (C) 2018 Ben McGinnes <[email protected]>
+#
+# This program is free software; you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 2 of the License, or (at your option) any later
+# version.
+#
+# This program is free software; you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation; either version 2.1 of the License, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU General Public License and the GNU
+# Lesser General Public Licensefor more details.
+#
+# You should have received a copy of the GNU General Public License and the GNU
+# Lesser General Public along with this program; if not, see
+# <http://www.gnu.org/licenses/>.
+
+import gpg
+import os.path
+
+print("""
+This script revokes a user ID on an existing key.
+
+The gpg-agent and pinentry are invoked to enter the passphrase.
+""")
+
+c = gpg.Context()
+
+homedir = input("Enter the GPG configuration directory path (optional): ")
+fpr0 = input("Enter the fingerprint of the key to modify: ")
+uid_name = input("Enter the name of the user ID: ")
+uid_email = input("Enter the email address of the user ID: ")
+uid_cmnt = input("Enter a comment to include (optional): ")
+
+if homedir.startswith("~"):
+    if os.path.exists(os.path.expanduser(homedir)) is True:
+        c.home_dir = os.path.expanduser(homedir)
+    else:
+        pass
+elif os.path.exists(homedir) is True:
+    c.home_dir = homedir
+else:
+    pass
+
+fpr = "".join(fpr0.split())
+
+if len(uid_cmnt) > 0:
+    userid = "{0} ({1}) <{2}>".format(uid_name, uid_cmnt, uid_email)
+else:
+    userid = "{0} <{2}>".format(uid_name, uid_email)
+
+key = c.get_key(fpr, secret=True)
+c.key_revoke_uid(key, userid)
diff --git a/lang/python/examples/howto/sign-key.py b/lang/python/examples/howto/sign-key.py
new file mode 100755
index 00000000..b1afe13c
--- /dev/null
+++ b/lang/python/examples/howto/sign-key.py
@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from __future__ import absolute_import, division, unicode_literals
+
+# Copyright (C) 2018 Ben McGinnes <[email protected]>
+#
+# This program is free software; you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 2 of the License, or (at your option) any later
+# version.
+#
+# This program is free software; you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation; either version 2.1 of the License, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU General Public License and the GNU
+# Lesser General Public Licensefor more details.
+#
+# You should have received a copy of the GNU General Public License and the GNU
+# Lesser General Public along with this program; if not, see
+# <http://www.gnu.org/licenses/>.
+
+import gpg
+import os.path
+
+print("""
+This script signs or certifies a key.
+
+The gpg-agent and pinentry are invoked to enter the passphrase.
+""")
+
+c = gpg.Context()
+
+homedir = input("Enter the GPG configuration directory path (optional): ")
+fpr0 = input("Enter the fingerprint of the key to sign: ")
+userid = input("Enter the UID to sign (case sensitive, optional): ")
+sig_type = input("Enter the certification type (local or normal): ")
+
+if homedir.startswith("~"):
+    if os.path.exists(os.path.expanduser(homedir)) is True:
+        c.home_dir = os.path.expanduser(homedir)
+    else:
+        pass
+elif os.path.exists(homedir) is True:
+    c.home_dir = homedir
+else:
+    pass
+
+fpr = "".join(fpr0.split())
+key = c.get_key(fpr, secret=False)
+
+if len(userid) > 0 and sig_type.lower() == "local":
+    c.key_sign(key, uids=userid, local=True)
+elif len(userid) > 0 and sig_type.lower() != "local":
+    c.key_sign(key, uids=userid)
+elif len(userid) == 0 and sig_type.lower() == "local":
+    c.key_sign(key, local=True)
+else:
+    c.key_sign(key)
diff --git a/lang/python/examples/howto/temp-homedir-config.py b/lang/python/examples/howto/temp-homedir-config.py
index 368cace1..ddd79327 100755
--- a/lang/python/examples/howto/temp-homedir-config.py
+++ b/lang/python/examples/howto/temp-homedir-config.py
@@ -69,6 +69,10 @@ personal-digest-preferences SHA512 SHA384 SHA256 SHA224 RIPEMD160 SHA1
 personal-compress-preferences ZLIB BZIP2 ZIP Uncompressed
 """
 
+agentconf = """# gpg-agent.conf settings for key generation:
+default-cache-ttl 300
+"""
+
 if len(sys.argv) == 1:
     print(intro)
     new_homedir = input("Enter the temporary gnupg homedir name: ")
@@ -107,9 +111,12 @@ else:
     print("Creating the {0} directory.".format(nh))
     os.mkdir(nh)
     os.chmod(nh, 0o700)
-    with open("{0}/{1}".format(nh, "gpg.conf"), "w") as f:
-        f.write(gpgconf)
+    with open("{0}/{1}".format(nh, "gpg.conf"), "w") as f1:
+        f1.write(gpgconf)
     os.chmod("{0}/{1}".format(nh, "gpg.conf"), 0o600)
+    with open("{0}/{1}".format(nh, "gpg-agent.conf"), "w") as f2:
+        f2.write(gpgconf)
+    os.chmod("{0}/{1}".format(nh, "gpg-agent.conf"), 0o600)
     print("""You may now use the {0} directory as an alternative GPG homedir:
 
 gpg --homedir {0}