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

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 <ben@gnupg.org>}
+#+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,
+			      sign=True, always_trust=True, add_encrypt_to=True)
-                                                  add_encrypt_to=True)
 
       with open("secret_plans.txt.asc", "wb") as afile:
 	  afile.write(ciphertext)
@@ -629,7 +629,8 @@
 	      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)):
@@ -638,7 +639,8 @@
 		  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
 
@@ -669,8 +671,10 @@
 
      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)
+
      with open(newfile, "wb") as nfile:
 	 nfile.write(plaintext)
    #+end_src
@@ -1078,8 +1082,8 @@
      c.home_dir = "~/.gnupg-dm"
      userid = "Danger Mouse <dm@secret.example.net>"
 
-     dmkey = c.create_key(userid, algorithm = "rsa3072", expires_in = 31536000,
+     dmkey = c.create_key(userid, algorithm="rsa3072", expires_in=31536000,
-			  sign = True, certify = True)
+			  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)
+     key = c.get_key(dmkey.fpr, secret=True)
-     dmsub = c.create_subkey(key, algorithm = "rsa3072", expires_in = 15768000,
+     dmsub = c.create_subkey(key, algorithm="rsa3072", expires_in=15768000,
-			     encrypt = True)
+			     encrypt=True)
    #+end_src
 
    As with the primary key, the results here can be checked with:
@@ -1210,6 +1214,12 @@
    :CUSTOM_ID: keygen-uids
    :END:
 
+
+*** Adding User IDs
+    :PROPERTIES:
+    :CUSTOM_ID: keygen-uids-add
+    :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
@@ -1222,7 +1232,7 @@
       c.home_dir = "~/.gnupg-dm"
 
       dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA"
-     key = c.get_key(dmfpr, secret = True)
+      key = c.get_key(dmfpr, secret=True)
       uid = "Danger Mouse <danger.mouse@secret.example.net>"
 
       c.key_add_uid(key, uid)
@@ -1244,6 +1254,28 @@
     #+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 <danger.mouse@secret.example.net>"
+
+      c.key_revoke_uid(key, uid)
+    #+end_src
+
+
 ** Key certification
    :PROPERTIES:
    :CUSTOM_ID: key-sign
@@ -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 <dm@secret.example.net>"
 
      dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA"
-     key = c.get_key(dmfpr, secret = True)
+     key = c.get_key(dmfpr, secret=True)
-     c.key_sign(key, uids = uid, expires_in = 2764800)
+     c.key_sign(key, uids=uid, expires_in=2764800)
    #+end_src
 
 

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 <ben@gnupg.org>
+#
+# 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)

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 <ben@gnupg.org>
+#
+# 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)

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 <ben@gnupg.org>
+#
+# 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)

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 <ben@gnupg.org>
+#
+# 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)

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:
+    with open("{0}/{1}".format(nh, "gpg.conf"), "w") as f1:
-        f.write(gpgconf)
+        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}