Merge branch 'master' of ssh+git://playfair.gnupg.org/git/gpgme

* Also fixed a small grammatical error highlighted by a merge conflict
  (in the python bindings howto).

5 files changed, 408 insertions, 0 deletions

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
new file mode 100755
index 00000000..ddd79327
--- /dev/null
+++ b/lang/python/examples/howto/temp-homedir-config.py
@@ -0,0 +1,126 @@
+#!/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 os
+import os.path
+import sys
+
+intro = """
+This script creates a temporary directory to use as a homedir for
+testing key generation tasks with the correct permissions, along
+with a gpg.conf file containing the same configuration options
+listed in the HOWTO.
+
+You may wish to change the order of the cipher preferences or
+remove those not relevant to your installation.  These
+configuration parameters assume that all ciphers and digests are
+installed and available rather than limiting to the default
+ciphers and digests.
+
+The script prompts for a directory name to be installed as a hidden
+directory in the user's home directory on POSIX systems.  So if you
+enter "gnupg-temp" on a Linux, BSD or OS X system, it will create
+"~/.gnupg-temp" (you do not need to enter the leading dot).
+
+This script has not been tested on Windows systems and may have
+unpredictable results.  That said, it will not delete or copy over
+existing data.
+
+If the directory already exists, the script will terminate with a
+message telling you to specify a new directory name.  There is no
+default directory name.
+"""
+
+gpgconf = """# gpg.conf settings for key generation:
+expert
+allow-freeform-uid
+allow-secret-key-import
+trust-model tofu+pgp
+tofu-default-policy unknown
+enable-large-rsa
+enable-dsa2
+cert-digest-algo SHA512
+default-preference-list TWOFISH CAMELLIA256 AES256 CAMELLIA192 AES192 CAMELLIA128 AES BLOWFISH IDEA CAST5 3DES SHA512 SHA384 SHA256 SHA224 RIPEMD160 SHA1 ZLIB BZIP2 ZIP Uncompressed
+personal-cipher-preferences TWOFISH CAMELLIA256 AES256 CAMELLIA192 AES192 CAMELLIA128 AES BLOWFISH IDEA CAST5 3DES
+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: ")
+elif len(sys.argv) == 2:
+    new_homedir = sys.argv[1]
+else:
+    new_homedir = " ".join(sys.argv[1:])
+
+userdir = os.path.expanduser("~")
+
+if new_homedir.startswith("~"):
+    new_homdir.replace("~", "")
+else:
+    pass
+
+if new_homedir.startswith("/"):
+    new_homdir.replace("/", "")
+else:
+    pass
+
+if new_homedir.startswith("."):
+    new_homdir.replace(".", "_")
+else:
+    pass
+
+if new_homedir.count(" ") > 0:
+    new_homedir.replace(" ", "_")
+else:
+    pass
+
+nh = "{0}/.{1}".format(userdir, new_homedir)
+
+if os.path.exists(nh) is True:
+    print("The {0} directory already exists.".format(nh))
+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 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}
+gpg --homedir --full-gen-key
+
+Or with GPGME scripts, including the GPGME Python bindings.
+""")